> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GuidesHeadlines

> GuidesHeadlines React and JS widgets used to display Algolia's Guides Headlines.

## React

The `GuidesHeadlines` widget lets you reference and render different guides on your website.

### Installation

The Algolia Guides React package is available on the [npm](https://www.npmjs.com/package/@algolia/generative-experiences-react) registry.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/generative-experiences-react
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/generative-experiences-react
  ```
</CodeGroup>

### Usage

```jsx React icon=code theme={"system"}
import { createClient } from "@algolia/generative-experiences-api-client";
import { GuidesHeadlines } from "@algolia/generative-experiences-react";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

function App({ userToken, category }) {
  //...

  return (
    <GuidesHeadlines
      showFeedback
      userToken={userToken}
      maxHeadlines={6}
      client={client}
      category={category}
      showImmediate
      searchParams={{
        page: 0,
        filters
      }}
    />
  );
}
```

### Parameters

<ParamField body="client" type="GSEClient" required>
  The initialized Algolia Generative Experiences client.
</ParamField>

<ParamField body="category" type="string" required>
  The category used for retrieving the headlines.
</ParamField>

<ParamField body="maxHeadlines" type="number" default={4}>
  The number of headlines to display (between 1 and 1000).
</ParamField>

<ParamField body="onlyPublished" type="boolean" default={true}>
  Whether to only return headlines with generated content.
</ParamField>

<ParamField body="showImmediate" type="boolean" default={true}>
  Whether to generate and display the headlines on load.
</ParamField>

<ParamField body="showFeedback" type="boolean" default={false}>
  Whether to show the feedback widget.
  If true, you also need to provide a `userToken`.
</ParamField>

<ParamField body="userToken" type="string">
  The user token needed for computing feedback.
  Required if `showFeedback` is `true`.
</ParamField>

<ParamField body="searchParams" type="SearchParamsObject">
  Search parameters that are applied when fetching headlines. Can be used for pagination or custom filtering.

  Not all search parameters are supported. Some parameters are ignored to ensure the correct functioning of the widget: `facetFilters`, `hitsPerPage`, `optionalFilters`, `attributesToHighlight` and `getRankingInfo`.

  For more information, see [API parameters](/doc/api-reference/search-api-parameters).
</ParamField>

<ParamField body="children" type="(props: ChildrenProps) => JSX.Element">
  A render function to fully customize what's displayed.

  The default implementation is:

  ```jsx React icon=code theme={"system"}
  function defaultRender(props) {
    return (
      <section
        className={cx(
          "ais-GuideHeadlinesContent-wrapper",
          props.classNames?.wrapper,
        )}
      >
        <props.View />
      </section>
    );
  }
  ```
</ParamField>

<ParamField body="view" type="ViewProps">
  The view component into which your guide headlines will be rendered.

  The default implementation is:

  ```jsx React icon=code theme={"system"}
  function ListView(props) {
    return (
      <div
        className={cx(
          "ais-GuideHeadlinesContent-container",
          props.classNames?.container,
        )}
      >
        {props.items.map((item) => (
          <div
            key={item.objectID}
            className={cx(
              "ais-GuideHeadlinesContent-item",
              props.classNames?.item,
            )}
          >
            <props.itemComponent
              createElement={createElement}
              Fragment={Fragment}
              classNames={props.classNames}
              item={item}
              getters={props.getters}
            />
          </div>
        ))}
        {props.showFeedback && (
          <props.feedbackComponent
            castFeedback={props.castFeedback}
            objectIDs={props.items.map((item) => item.objectID)}
            voteTarget="headline"
            alreadyCast={props.alreadyCast}
            createElement={createElement}
            Fragment={Fragment}
          />
        )}
      </div>
    );
  }
  ```
</ParamField>

<ParamField body="itemComponent" type="({ item, createElement, Fragment, html }) => JSX.Element | VNode | VNode[]">
  Component to display the headlines.
</ParamField>

<ParamField body="classNames" type="HeadlinesButtonClassNames">
  The class names for the component.

  ```ts TypeScript icon=code theme={"system"}
  type HeadlinesButtonClassNames = Partial<{
    wrapper?: string;
    container?: string;
    itemsContainer?: string;
    item?: string;
    itemContent?: string;
    itemTitle?: string;
    itemDescription?: string;
    itemImage?: string;
    list?: string;
    readMore?: string;
  }>;
  ```
</ParamField>

## JavaScript

The `guidesHeadlines` widget lets you reference and render different guides on your website.

### Installation

The Algolia Guides JavaScript package is available on the [npm](https://www.npmjs.com/package/@algolia/generative-experiences-js) registry.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/generative-experiences-js
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/generative-experiences-js
  ```
</CodeGroup>

### Usage

```js JavaScript icon=code theme={"system"}
import { createClient } from "@algolia/generative-experiences-api-client";
import { guidesHeadlines } from "@algolia/generative-experiences-js";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

guidesHeadlines({
  container: "#headlines",
  client: client,
  userToken: "test-user",
  showImmediate: true,
  showFeedback: true,
  category: "category",
});
```

### Parameters

<ParamField body="client" type="GSEClient" required>
  The initialized Algolia Generative Experiences client.
</ParamField>

<ParamField body="category" type="string" required>
  The category used for retrieving the headlines.
</ParamField>

<ParamField body="maxHeadlines" type="number" default={4}>
  The number of headlines to display (between 1 and 1000).
</ParamField>

<ParamField body="onlyPublished" type="boolean" default={true}>
  Whether to only return headlines with generated content.
</ParamField>

<ParamField body="showImmediate" type="boolean" default={true}>
  Whether to generate and display the headlines on load.
</ParamField>

<ParamField body="showFeedback" type="boolean" default={false}>
  Whether to show the feedback widget.
  If true, you also need to provide a `userToken`.
</ParamField>

<ParamField body="userToken" type="string">
  The user token needed for computing feedback.
  Required if `showFeedback` is `true`.
</ParamField>

<ParamField body="children" type="(props: ChildrenProps) => JSX.Element">
  A render function to fully customize what's displayed.

  The default implementation is:

  ```jsx JavaScript icon=code theme={"system"}
  function defaultRender(props) {
    return (
      <section
        className={cx(
          "ais-GuideHeadlinesContent-wrapper",
          props.classNames?.wrapper,
        )}
      >
        <props.View />
      </section>
    );
  }
  ```
</ParamField>

<ParamField body="view" type="ViewProps">
  The view component into which your guide headlines will be rendered.

  The default implementation is:

  ```jsx JavaScript icon=code theme={"system"}
  function ListView(props) {
    return (
      <div
        className={cx(
          "ais-GuideHeadlinesContent-container",
          props.classNames?.container,
        )}
      >
        {props.items.map((item) => (
          <div
            key={item.objectID}
            className={cx(
              "ais-GuideHeadlinesContent-item",
              props.classNames?.item,
            )}
          >
            <props.itemComponent
              createElement={createElement}
              Fragment={Fragment}
              classNames={props.classNames}
              item={item}
              getters={props.getters}
            />
          </div>
        ))}
        {props.showFeedback && (
          <props.feedbackComponent
            castFeedback={props.castFeedback}
            objectIDs={props.items.map((item) => item.objectID)}
            voteTarget="headline"
            alreadyCast={props.alreadyCast}
            createElement={createElement}
            Fragment={Fragment}
          />
        )}
      </div>
    );
  }
  ```
</ParamField>

<ParamField body="itemComponent" type="({ item, createElement, Fragment, html }) => JSX.Element | VNode | VNode[]">
  Component to display the headlines.
</ParamField>

<ParamField body="classNames" type="HeadlinesButtonClassNames">
  The class names for the component.

  ```ts TypeScript icon=code theme={"system"}
  type HeadlinesButtonClassNames = Partial<{
    wrapper?: string;
    container?: string;
    itemsContainer?: string;
    item?: string;
    itemContent?: string;
    itemTitle?: string;
    itemDescription?: string;
    itemImage?: string;
    list?: string;
    readMore?: string;
  }>;
  ```
</ParamField>