--- 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`. ```bash yarn add @docsearch/js@4 # or with npm npm install @docsearch/js@4 ``` ### Without package manager Include CSS in your website's `` ```html ``` And the JavaScript at the end of your ``: ```html ``` ```bash yarn add @docsearch/react@4 # or npm install @docsearch/react@4 ``` ### Without package manager Include CSS in your website's ``: ```html ``` And the JavaScript at the end of your ``: ```html ``` ### Optimize first query performance Enhance your users' first search experience by using `preconnect`, see [Performance optimization](#preconnect) below ## Implementation DocSearch requires a dedicated container in your HTML ```html

``` 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. Integrating DocSearch into your React app is straightforward: ```jsx App.js import { DocSearch } from '@docsearch/react'; import '@docsearch/css'; function App() { return ( ); } export default App; ``` DocSearch generates a fully accessible search input out-of-the-box. ### Quick Testing (without credentials) If you'd like to test DocSearch immediately without your own credentials, use our demo configuration: ```js docsearch({ appId: 'PMZUYBQDAK', apiKey: '24b09689d5b4223813d9b8e48563c8f6', indexName: 'docsearch', askAi: 'askAIDemo', }); ``` ```jsx ``` 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): ```js docsearch({ appId: 'YOUR_APP_ID', indexName: 'YOUR_INDEX_NAME', apiKey: 'YOUR_SEARCH_API_KEY', askAi: 'YOUR_ALGOLIA_ASSISTANT_ID', }); ``` ```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 }, }); ``` - 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. ```js docsearch({ searchParameters: { facetFilters: ['language:en', 'version:1.0.0'], }, }); ``` ```jsx ``` #### 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. ::: ```js docsearch({ askAi: { assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID', searchParameters: { facetFilters: ['language:en', 'version:1.0.0'], }, }, }); ``` ```jsx ``` :::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. ```diff docsearch({ // other options + insights: true, }); ``` ```diff ``` ## Performance optimization ### Preconnect Improve the loading speed of your initial search request by adding this snippet into your website's `` section: ```html ``` 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