Version: Stable (v5.x)

Migrate from DocSearch v4

DocSearch v5 separates keyword search from the AI experience and uses Agent Studio for Ask AI. Plan the migration around the experience your site provides.

Review the complete v5 breaking changes before releasing.

1. Upgrade the beta packages

Upgrade every DocSearch package in the integration together with the ^5 range.

React
JavaScript

npm
Yarn
pnpm
Bun

npm install @docsearch/react@^5 @docsearch/css@^5

yarn add @docsearch/react@^5 @docsearch/css@^5

pnpm add @docsearch/react@^5 @docsearch/css@^5

bun add @docsearch/react@^5 @docsearch/css@^5

npm
Yarn
pnpm
Bun

npm install @docsearch/js@^5 @docsearch/css@^5

yarn add @docsearch/js@^5 @docsearch/css@^5

pnpm add @docsearch/js@^5 @docsearch/css@^5

bun add @docsearch/js@^5 @docsearch/css@^5

If you use the Composable API or Sidepanel, also upgrade @docsearch/core@^5, @docsearch/modal@^5, @docsearch/sidepanel@^5, or @docsearch/sidepanel-js@^5.

2. Choose keyword-only or AI-capable search

JavaScript without Ask AI

The v4 root export rendered the combined component. In v5, the root export is AI-capable and the /docsearch subpath is keyword-only.

Change the import:

app.js
-import docsearch from '@docsearch/js';
+import docsearch from '@docsearch/js/docsearch';

Your keyword options can remain unchanged while you migrate deprecated options in a later step.

For a CDN integration, replace the root bundle with the keyword-only UMD file:

index.html
-<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@4"></script>
+<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@^5/dist/umd/docsearch.js"></script>

JavaScript with Ask AI

Keep the root import. It now renders the AI-capable DocSearchAI component:

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

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: {
    agentId: 'YOUR_AGENT_ID',
  },
});

For a CDN integration, use dist/umd/index.js. It exposes window.docsearch, as v4 did.

React without Ask AI

Keep DocSearch, but remove any AI props. In v5 it renders keyword search only:

Search.jsx
import { DocSearch } from '@docsearch/react';

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['YOUR_INDEX_NAME']}
/>;

React with Ask AI

Replace DocSearch with DocSearchAI:

Search.jsx
-import { DocSearch } from '@docsearch/react';
+import { DocSearchAI } from '@docsearch/react';

-<DocSearch
+<DocSearchAI
   appId="YOUR_APP_ID"
   apiKey="YOUR_SEARCH_API_KEY"
   indices={['YOUR_INDEX_NAME']}
   askAi={{ agentId: 'YOUR_AGENT_ID' }}
 />

DocSearchAI requires askAi. The string shorthand remains supported:

Search.jsx
<DocSearchAI askAi="YOUR_AGENT_ID" {...searchProps} />

3. Move Ask AI to Agent Studio

V5 removes the legacy Ask AI token and chat transport. Create the agent in Agent Studio before switching production traffic. If you already have an Ask AI assistant, follow Migrate Ask AI to Agent Studio.

Rename assistantId to agentId. Remove agentStudio from askAi. Agent Studio is the only Ask AI backend in v5.

app.js
 askAi: {
-  assistantId: 'YOUR_ASSISTANT_ID',
+  agentId: 'YOUR_AGENT_ID',
-  agentStudio: true,
 }

The v4 Agent Studio form keyed search parameters by index name. V5 keeps that shape and removes the legacy flat form:

app.js
 askAi: {
-  assistantId: 'YOUR_ASSISTANT_ID',
+  agentId: 'YOUR_AGENT_ID',
   searchParameters: {
-    filters: 'language:en',
-    attributesToRetrieve: ['title', 'content', 'url'],
+    docs: {
+      filters: 'language:en',
+      attributesToRetrieve: ['title', 'content', 'url'],
+    },
   },
 }

Agent Studio search parameters support filters, attributesToRetrieve, restrictSearchableAttributes, and distinct. They don't support facetFilters in this object. Put fixed facet conditions in filters, or configure dynamic Agent Studio indices.

V5 adds askAi.indices, askAi.tools, askAi.memory, and askAi.promptSuggestions. Keep all Agent Studio configuration inside askAi. Keep interceptAskAiEvent at the component or docsearch() root because it controls view routing.

4. Move keyword configuration to `indices`

indexName and root searchParameters both have been removed in v5.

app.js
 docsearch({
   appId: 'YOUR_APP_ID',
   apiKey: 'YOUR_SEARCH_API_KEY',
-  indexName: 'docs',
-  searchParameters: {
-    facetFilters: ['language:en'],
-  },
+  indices: [
+    {
+      name: 'docs',
+      searchParameters: {
+        facetFilters: ['language:en'],
+      },
+    },
+  ],
 });

Use one item per index. DocSearch queries them in array order.

5. Update result customization

Existing transformItems, hitComponent, resultsFooterComponent, transformSearchClient, navigation, Insights, and translation props remain available.

V5 changes the result markup and adds breadcrumbs, source sections, facets, and badges. Review custom CSS, DOM selectors, screenshots, and tests that depend on v4 markup.

To show a badge from a custom record property, add the property to the per-index attributesToRetrieve, then set resultBadgeKey:

Search.jsx
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'docs',
      searchParameters: {
        attributesToRetrieve: [
          'hierarchy.lvl0',
          'hierarchy.lvl1',
          'hierarchy.lvl2',
          'hierarchy.lvl3',
          'hierarchy.lvl4',
          'hierarchy.lvl5',
          'hierarchy.lvl6',
          'content',
          'type',
          'url',
          'version',
        ],
      },
    },
  ]}
  resultBadgeKey="version"
/>

6. Verify styles and package exports

The full stylesheet remains available from @docsearch/css and the CDN dist/style.css file:

app.js
import '@docsearch/css';

The React package adds split style entries for variables, button, modal, Ask AI, and Sidepanel. See Styling.

@docsearch/js now defines an exports map. Replace unsupported deep imports with @docsearch/js or @docsearch/js/docsearch. Continue to use documented React subpaths such as @docsearch/react/button, /modal, /sidepanel, and /version; their generated file names changed, but the package subpaths remain the public API.

7. Verify programmatic controls

The JavaScript function returns a DocSearchInstance with open, close, openAskAi, destroy, isReady, and isOpen. Use openAskAi only with the default AI-capable entry.

React forwards DocSearchRef. It also exposes openSidepanel, isSidepanelOpen, and isSidepanelSupported for hybrid mode.

Test these cases before release:

Open and close by button, Ctrl/Cmd+K, /, and Escape.
Search every configured index and apply every facet.
Open Ask AI, send follow-up questions, submit feedback, and restore a conversation.
Exercise any custom tools and memory authentication.
Verify custom hit links, result footers, translations, badges, and Insights events.
Verify mobile behavior. Hybrid mode uses the modal instead of the Sidepanel on mobile.

8. Update framework integrations

If Docusaurus manages DocSearch configuration, follow the Docusaurus adapter guide. For custom provider, button, and modal layouts, review the Composable API.

1. Upgrade the beta packages​

2. Choose keyword-only or AI-capable search​

JavaScript without Ask AI​

JavaScript with Ask AI​

React without Ask AI​

React with Ask AI​

3. Move Ask AI to Agent Studio​

4. Move keyword configuration to indices​

5. Update result customization​

6. Verify styles and package exports​

7. Verify programmatic controls​

8. Update framework integrations​