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

# Integrate Guides into your website

> A technical overview of how to integrate Guides into your website

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

export const ApplicationID = () => <Tooltip tip="A unique alphanumeric string that identifies an Algolia application." cta="Application ID (dashboard)" href="https://dashboard.algolia.com/account/api-keys">
    application ID
  </Tooltip>;

export const Application = () => <Tooltip tip="An Algolia application is a self-contained environment with its own indices, configuration, and API keys. Applications don't share data or settings with each other.">
    application
  </Tooltip>;

export const APIKey = () => <Tooltip tip="An alphanumeric string that controls access to the Algolia APIs. It defines what actions are allowed, such as searching an index or adding new records." cta="API key" href="/doc/guides/security/api-keys">
    API key
  </Tooltip>;

After creating a set of guides,
you need to integrate them into your website.

## Before you begin

To integrate your guides, you need frontend development proficiency with HTML, CSS, JavaScript, and React.
You should also have [created your guides](/doc/guides/algolia-ai/generative-experiences/guides/generating-guides).

On this page, React is used to illustrate the integration process.
However, the generative experiences client offers widgets for React and JavaScript.
For more information, see [Alternative implementations](/doc/guides/algolia-ai/generative-experiences/ui-library/alternatives).

## Installation

Install the `@algolia/generative-experiences-react` package:

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

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

### Set up the commerce client

The commerce client interacts with the Algolia Commerce API and is crucial for fetching the necessary data for the widgets:

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

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

**Parameters**

* `appId`. Your Algolia <ApplicationID />.
* `indexName`. The Algolia <Index /> used for generating and displaying guides.
* `searchOnlyAPIKey`. The Algolia search <APIKey /> needed for reading index data. ACL needed: `search`.
* `region`. The region of your Algolia <Application />, either `eu` or `us`. Default: `us`.

## Display guide

Guides contain content and headlines.

### Display guide content

To show the content of a guide, use the `GuideContent` widget.
For more information, see [`GuideContent`](/doc/guides/algolia-ai/generative-experiences/ui-library/content).

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

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

const HitComponent = ({ hit }: { hit: any }) => {
  return (
    <div>
      <p>{hit.name}</p>
      <img src={hit.image} alt="" />
    </div>
  );
};

function App({ currentObjectID, userToken }) {
  //...
  return (
    <GuideContent
      client={client}
      showFeedback
      userToken={userToken}
      objectID={currentObjectID}
      itemComponent={({ hit }) => <HitComponent hit={hit} />}
    />
  );
}
```

<img src="https://mintcdn.com/algolia/aN8Lr52w2iijNnTe/images/guides/algolia-ai/generative-experiences/guide-content-related.png?fit=max&auto=format&n=aN8Lr52w2iijNnTe&q=85&s=72e2634fedf1861d91e550f2756b3f4d" alt="Screenshot of a webpage displaying a guide on buying and maintaining a QLED TV, with related product recommendations." width="1151" height="1384" data-path="images/guides/algolia-ai/generative-experiences/guide-content-related.png" />

### Display guide headlines

To reference your website's guides, use the `GuidesHeadlines` widget.
This widget can be embedded in your home page, product detail page,
or search pages, and customized to display headlines based on categories or specific <Records />.

For more information, see [`GuidesHeadlines`](/doc/guides/algolia-ai/generative-experiences/ui-library/headlines).

```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",
});

function App({ userToken, category }) {
  //...
  return (
    <GuidesHeadlines
      showFeedback
      userToken={userToken}
      client={client}
      category={category}
      showImmediate
    />
  );
}
```

<img src="https://mintcdn.com/algolia/aN8Lr52w2iijNnTe/images/guides/algolia-ai/generative-experiences/guides-cells.png?fit=max&auto=format&n=aN8Lr52w2iijNnTe&q=85&s=0412a5ef613d9af1443656d29bc59e3e" alt="Screenshot of a webpage showing four guide headlines under the 'Laptops' section, each with a title, description, and 'Read more' button." width="1211" height="989" data-path="images/guides/algolia-ai/generative-experiences/guides-cells.png" />

## Gather feedback

To gather feedback on the Guides you can use the `GuidesFeedback` widget.
You can use this widget directly in a [Guide Content](#display-guide-content) page,
or when you are displaying the [Guide Headlines](#display-guide-headlines),
by passing `showFeedback` parameters in the `GuideContent` or `GuidesHeadlines` widgets.
Or you can add it and customize it separately, using the `GuidesFeedback` widget.

For more information, see [`GuidesFeedback`](/doc/guides/algolia-ai/generative-experiences/ui-library/feedback).

<Note>
  This feature uses the Insights API to gather events related to Guides feedback.
  This requires a [user token](/doc/guides/sending-events/concepts/usertoken).
</Note>

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

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

function Page({ objectID, userToken }) {
  //...
  return (
    //...
    <GuidesFeedback
      client={client}
      objectIDs={[objectID]}
      userToken={userToken}
    />
  );
}
```

## Display website-specific content

Some of the generated guides may contain placeholders for website-specific content.
These are used for the links to the product pages, guide pages as well as images.

To replace these placeholders with your website-specific content,
use the `getters` parameter.

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

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

const customGetters = {
  /**
   * URL for a specific guide.
   */
  guideURL: (objectID) => `/shopping-guide/${objectID}`,
  /**
   * URL for a specific product.
   */
  objectURL: (objectID) => `/product/${objectID}`,
  /**
   * List of images for a product.
   */
  images: (object) =>
    object.images.map((image) => ({ src: image.url, alt: image.alt })),
};

const HitComponent = ({ hit }: { hit: any }) => {
  return (
    <div>
      <p>{hit.name}</p>
      <img src={hit.image} alt="" />
    </div>
  );
};

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

  return (
    <GuideContent
      client={gseClient}
      showFeedback
      userToken={userToken}
      objectID={currentObjectID}
      itemComponent={({ hit }) => <HitComponent hit={hit} />}
      getters={customGetters}
    />
  );
}
```

### Parameters

* `guideURL`.
  Returns the URL for a specific guide.
  This is used to link to the guide page from the guide headlines widget.
  The expected output is a string that represents the URL of the guide page.
* `objectURL`.
  Returns the URL for a specific product.
  This is used to link to the product page from the guide content widget.
  The expected output is a string that represents the URL of the product page.
* `images`.
  Returns a list of images for a product.
  This is used to display images in the guide headlines and guide content widgets.
  The expected output is an array of objects, each containing the `src` and `alt` properties.

## Customize styles

The widgets aren't styled by default.
You can style them with the `classNames` property or by applying your CSS to the existing classes.

### With the `classNames` property

Use the `classNames` property to add classes to the widgets.

```jsx React icon=code theme={"system"}
<ShoppingGuideHeadlines
  classNames={{
    wrapper: "YOUR_WRAPPER_CLASS",
    container: "YOUR_CONTAINER_CLASS",
    item: "YOUR_ITEM_CLASS",
  }}
/>;
```

You can also use the class names that are already set to style the widget.

### With Tailwind CSS

To integrate the widgets with Tailwind,
include the `@tailwindcss/typography` plugin in your `tailwind.config.js` and add the following CSS to your project.

```css CSS icon=paintbrush theme={"system"}
.ais-NoWrap {
  @apply whitespace-nowrap;
}

.ais-ScreenReaderOnly {
  @apply sr-only;
}

/* display headlines */
.ais-GuideHeadlinesContent-wrapper {
  @apply rounded p-4 border border-gray-100 shadow gap-2;
}

.ais-GuideHeadlinesContent-container {
  @apply flex flex-col items-end;
}

.ais-GuideHeadlinesContent-itemsContainer {
  @apply flex items-center gap-6;
}

.ais-GuideHeadlinesContent-readMore {
  @apply flex text-white py-2 mt-8 border-2 bg-blue-700 rounded-md items-center w-full justify-center;
}

.ais-GuideHeadlinesContent-item {
  @apply bg-neutral-100 rounded p-4 space-y-3 flex justify-between min-h-[420px];
}

.ais-GuideHeadlinesContent-itemContent {
  @apply mt-5;
}

.ais-GuideHeadlinesContent-itemTitle {
  @apply text-blue-800 font-semibold line-clamp-2 h-12;
}

.ais-GuideHeadlinesContent-itemDescription {
  @apply line-clamp-4 text-base mt-2;
}

.ais-GuideHeadlinesContent-itemImage {
  @apply relative min-h-[120px] max-h-[120px] w-auto overflow-hidden mx-auto mt-4 aspect-square;
}

/* display content */
.ais-GuideContent-contentSection {
  @apply prose max-w-prose mx-auto px-4;
}

.ais-GuideContent {
  @apply mb-10 w-full;
}

.ais-GuideContent-heroImage {
  @apply mx-auto min-h-[200px] max-h-[250px] my-12;
}

.ais-GuideContent .ais-Feedback {
  @apply flex items-end justify-end mx-auto;
}

.ais-GuideContent-factorsList {
  @apply flex flex-wrap list-disc gap-x-2 justify-between w-full;
}

.ais-GuideContent-factorItem {
  @apply w-[45%];
}

.ais-GuideContent-relatedItemsSection {
  @apply prose max-w-none mx-auto px-4;
}

.ais-GuideContent-relatedItemsTitle {
  @apply max-w-prose mx-auto px-4;
}

.ais-GuideContent-relatedItemsListContainer {
  @apply max-w-prose mx-auto px-4;
}

.ais-GuideContent-relatedItemsList {
  @apply p-2 flex justify-between flex-wrap list-none;
}

/* display feedback */
.ais-Feedback {
  @apply text-gray-500 text-base max-w-prose mt-10;
}

.ais-feedbackContainer {
  @apply flex items-center gap-4;
}

.ais-Feedback-thanksWrapper {
  @apply flex items-center;
}

.ais-Feedback-labelWrapper {
  @apply flex space-x-2 items-center;
}

.ais-Feedback-labelIcon {
  @apply h-6 w-6 flex-shrink-0;
}

.ais-Feedback-button {
  @apply inline-block rounded font-semibold text-center shadow-sm transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 bg-white hover:bg-white border-2 border-gray-400 hover:border-gray-500 focus-visible:outline-gray-500 text-gray-400 hover:text-gray-500 px-2.5 py-1.5;
}

.ais-Feedback-buttonsWrapper {
  @apply flex space-x-3 items-center;
}

.ais-Feedback-buttonIcon {
  @apply h-4 w-4 stroke-2 flex-shrink-0;
}

/* error loading guide */
.ais-GuideContentError {
  @apply flex flex-col items-center text-center gap-y-4 max-w-prose mx-auto my-6;
}

.ais-GuideContentErrorTitle {
  @apply text-lg font-semibold;
}
```

## Next step

After creating the mechanism for displaying your guides,
[publish them](/doc/guides/algolia-ai/generative-experiences/guides/publishing-guides) to show them in your live environment.