docsearch/packages/website/versioned_docs/version-v4/docsearch.mdx

---
title: Getting Started with v4
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Introduction

DocSearch v4 provides a significant upgrade over previous versions, offering enhanced accessibility, responsiveness, and an improved search experience for your documentation. Built on [Algolia Autocomplete][1], DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.

## Installation

> Looking for the Composable API documentation? You can find it [here][17].

DocSearch packages are available on the [npm registry][10].

### Docusaurus users

If your docs site is powered by Docusaurus, use [`@docsearch/docusaurus-adapter`](/docs/docusaurus-adapter) for the latest DocSearch features (including new Ask AI capabilities such as sidepanel support), while keeping `@docusaurus/preset-classic`.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```bash
yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4
```

### Without package manager

Include CSS in your website's `<head>`

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
```

</TabItem>
<TabItem value="react">

```bash
yarn add @docsearch/react@4
# or
npm install @docsearch/react@4
```

### Without package manager

Include CSS in your website's `<head>`:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>
```

</TabItem>

</Tabs>

### Optimize first query performance

Enhance your users' first search experience by using `preconnect`, see [Performance optimization](#preconnect) below

## Implementation

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

DocSearch requires a dedicated container in your HTML

```html
<div id="docsearch"></div>
```

Initialize DocSearch by passing your container:

```js app.js
import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});
```

DocSearch generates an accessible, fully-functional search input for you automatically.

</TabItem>

<TabItem value="react">

Integrating DocSearch into your React app is straightforward:

```jsx App.js
import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;
```

DocSearch generates a fully accessible search input out-of-the-box.

</TabItem>

</Tabs>

### Quick Testing (without credentials)

If you'd like to test DocSearch immediately without your own credentials, use our demo configuration:

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
  askAi="askAIDemo"
/>
```

</TabItem>

</Tabs>

Or use our new dedicated [DocSearch Playground](https://community.algolia.com/docsearch-playground/)

### Using DocSearch with Ask AI

DocSearch v4 introduces support for Ask AI, Algolia's advanced, AI-powered search capability. Ask AI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation. You can also use the same `askAi` configuration object to route chat through Agent Studio.

To enable Ask AI, you can add your Algolia Assistant ID as a string, or use an object for more advanced configuration (such as specifying a different index, credentials, search parameters, or enabling Agent Studio):

<Tabs groupId="askai-format" defaultValue="string" values={[{ label: 'String', value: 'string' }, { label: 'Object', value: 'object' }]}>
<TabItem value="string">

```js
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});
```

</TabItem>
<TabItem value="object">

```js
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    indexName: 'YOUR_MARKDOWN_INDEX', // Optional: use a different index for Ask AI
    apiKey: 'YOUR_SEARCH_API_KEY',     // Optional: use a different API key for Ask AI
    appId: 'YOUR_APP_ID',              // Optional: use a different App ID for Ask AI
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'], // Optional: filter Ask AI context
    },
    suggestedQuestions: true // Optional: enable loading suggested questions on the Ask AI new conversation screen
  },
});
```

</TabItem>
</Tabs>

- Use the string form for a simple setup.
- Use the object form to customize which index, credentials, or filters Ask AI uses.
- The suggested questions feature is controlled on the [Dashboard](https://dashboard.algolia.com) in the Ask AI section.

### Using Agent Studio with DocSearch

To use [Algolia Agent Studio](https://www.algolia.com/doc/guides/algolia-ai/agent-studio) as the chat backend, set `agentStudio: true` inside the `askAi` object and pass your Agent Studio **agent ID** as `assistantId`. Full migration steps (v4, v5, and custom Ask AI API) are in [Migrate Ask AI to Agent Studio](/docs/v4/v4/migrating-askai-to-agent-studio).

```js
docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    agentStudio: true,
    searchParameters: {
      YOUR_INDEX_NAME: {
        filters: 'type:content AND language:en',
        attributesToRetrieve: ['title', 'content', 'url'],
        restrictSearchableAttributes: ['title', 'content'],
        distinct: 'url',
      },
    },
  },
});
```

- `agentStudio` is configured inside `askAi`, not as a top-level DocSearch prop.
- When `agentStudio: true`, `searchParameters` must be keyed by index name.
- Agent Studio search parameters support `filters`, `attributesToRetrieve`, `restrictSearchableAttributes`, and `distinct`.

### Filtering search results

#### Keyword search

If your website uses [DocSearch meta tags][13] or if you've added [custom variables to your config][14], you'll be able to use the [`facetFilters`][16] option to scope your search results to a [`facet`][15]

This is useful to limit the scope of the search to one language or one version.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  searchParameters={{
    facetFilters: ['language:en', 'version:1.0.0'],
  }}
/>
```

</TabItem>

</Tabs>

#### Ask AI

Filtering also applies when using Ask AI. This is useful to limit the scope of the LLM's search to only relevant results.

:::info
We recommend using the `facetFilters` option when using Ask AI with multiple languages or any multi-faceted index.
:::

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">
```js
docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
```
</TabItem>

<TabItem value="react">
```jsx
<DocSearch
  askAi={{
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  }}
/>
```
</TabItem>

</Tabs>

:::tip
You can use `facetFilters: ['type:content']` to ensure Ask AI only uses records where the `type` attribute is `content` (i.e., only records that actually have content). This is useful if your index contains records for navigation, metadata, or other non-content types.
:::

### Sending events

You can send search events to your DocSearch index by passing in the `insights` parameter when creating your DocSearch instance.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```diff
docsearch({
   // other options
+  insights: true,
});
```

</TabItem>

<TabItem value="react">

```diff
<DocSearch
  // other options
+  insights={true}
/>
```

</TabItem>

</Tabs>

## Performance optimization

### Preconnect

Improve the loading speed of your initial search request by adding this snippet into your website's `<head>` section:

```html
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
```

This helps the browser establish a quick connection with Algolia, enhancing user experience, especially on mobile devices.

[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
[2]: https://github.com/algolia/docsearch/
[3]: https://github.com/algolia/docsearch/tree/master
[4]: /docs/legacy/dropdown
[5]: /docs/integrations
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[7]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[8]: https://codesandbox.io/s/docsearch-js-v3-playground-z9oxj
[9]: https://codesandbox.io/s/docsearch-react-v3-playground-619yg
[10]: https://www.npmjs.com/
[11]: /docs/api#container
[12]: /docs/api
[13]: /docs/required-configuration#introduce-global-information-as-meta-tags
[14]: /docs/record-extractor#indexing-content-for-faceting
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
[17]: /docs/composable-api