docsearch Documentation

Technical Documentation: algolia/docsearch

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

DocSearch crawls your documentation, pushes the content to an Algolia index and provides a dropdown search experience on your website.

Preview Copy Chapter

Usage Copy Chapter

Don't have your Algolia credentials yet? Apply to DocSearch!

JavaScript Copy Section

Installation

bun add @docsearch/js@5
# or
npm install @docsearch/js@5

If you don’t want to use a package manager, you can use a standalone endpoint:

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

Get started

To get started, you need a container for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:

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

Then, insert DocSearch into it by calling the docsearch function and providing the container. It can be a CSS selector or an Element.

Make sure to provide a container (for example, a div), not an input. DocSearch generates a fully accessible search box for you.

import docsearch from '@docsearch/js';

import '@docsearch/css';

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

React Copy Section

Installation

bun add @docsearch/react@5
# or
npm install @docsearch/react@5

If you don’t want to use a package manager, you can use a standalone endpoint:

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

Get started

DocSearch generates a fully accessible search box for you.

import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices=["YOUR_ALGOLIA_INDEX"]
    />
  );
}

export default App;

Styling Copy Chapter

Read documentation →

MCP plugins Copy Chapter

Client plugins for the public DocSearch MCP endpoint are in mcp/plugins/docsearch. They connect ChatGPT, Codex, Cursor, and Claude Code to https://mcp.algolia.com/1/docsearch/mcp for current public developer documentation.

Related projects Copy Chapter

DocSearch is made of the following repositories:

• algolia/docsearch: DocSearch source code.
• algolia/docsearch/packages/website: DocSearch website and documentation.
• algolia/docsearch-configs: DocSearch websites configurations that DocSearch powers.
• algolia/docsearch-scraper: DocSearch crawler that extracts data from your documentation.

Used by Copy Chapter

DocSearch is used by Bootstrap, Cheerio, Element Plus, Authelia, MDX, VitePress and many more.

Generated with usedby.dev

License Copy Chapter

MIT

Packages Website Docs Agent Studio Getting Started (`packages/website/docs/agent-studio/getting-started.mdx`) Copy Section

title: Get started with Agent Studio Copy Chapter

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

DocSearch v5 uses Agent Studio as its only AI backend. The public option is still named askAi, so you can add AI without learning a second DocSearch configuration shape.

Don't add an agentStudio flag. There's no AI backend selector in v5.

If you already have an Ask AI assistant, see Migrate Ask AI to Agent Studio.

Before you begin Copy Chapter

1. Create and publish an Agent Studio agent.
2. Copy its agent ID. DocSearch calls this value agentId in its public API.
3. Create a Search API key that can search the indices used by DocSearch and Agent Studio. Don't expose an Admin API key.
4. Note your Algolia application ID and DocSearch index name.

Add DocSearch Copy Chapter

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

import { DocSearchAI } from '@docsearch/react';
import '@docsearch/css';

export function Search() {
  return (
    <DocSearchAI
      appId="YOUR_APPLICATION_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['YOUR_DOCSEARCH_INDEX']}
      askAi={{
        agentId: 'YOUR_AGENT_ID',
      }}
    />
  );
}

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

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

import docsearch from '@docsearch/js';
import '@docsearch/css';

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

Configure more Agent Studio features Copy Chapter

Use the askAi object to add:

• Dynamic indices
• Client-side and MCP tools
• User-scoped memory
• Suggested prompts and follow-ups
• Response feedback

Use the Docusaurus adapter Copy Chapter

The v5 Docusaurus adapter requires themeConfig.docsearch.askAi to be an object with agentId. It rejects the string shorthand and the removed agentStudio property. Keep appId, apiKey, and keyword-search indices at the top level.

See the Docusaurus adapter guide for its full configuration and validation rules.

Packages Website Docs Mcp Overview (`packages/website/docs/mcp/overview.mdx`) Copy Section

title: DocSearch MCP sidebar_label: Overview Copy Chapter

DocSearch MCP lets AI clients search public developer documentation in the DocSearch corpus.

Use it when an assistant needs information from published documentation instead of relying only on its training data. Connect an MCP-compatible client to this endpoint:

https://mcp.algolia.com/1/docsearch/mcp

The endpoint doesn't require authentication. You don't need an Algolia application ID, search API key, or DocSearch application.

What DocSearch MCP provides Copy Chapter

DocSearch MCP exposes documentation search through the Model Context Protocol. Your client calls its tools, receives ranked documentation excerpts and source URLs, and uses those results to answer your question.

Use DocSearch MCP for public documentation about libraries, frameworks, SDKs, APIs, CLI tools, and cloud services. It doesn't provide access to:

• Private or unpublished documentation
• Internal repositories
• DocSearch crawler or administration operations
• Algolia indices or credentials
• General programming advice outside the indexed documentation

How searches work Copy Chapter

For most searches, provide a product name and a focused question. DocSearch resolves the matching documentation set and searches it in one call.

Use the two-step workflow when a question covers several products or when you need to select the documentation set yourself. First resolve candidate sets, then query the selected set IDs.

Available tools Copy Chapter

`algolia_docsearch_search_docs` Copy Section

Use this one-shot tool for most searches. Set library to the official product, SDK, or platform name. Set query to the documentation question.

The tool resolves the best matching documentation set and returns ranked content. If the product name is ambiguous, it returns candidate documentation sets instead.

`algolia_docsearch_resolve_docset` Copy Section

Use this tool first in the manual workflow. It returns candidate documentation sets with a docset_id, title, description, and ranking signals.

`algolia_docsearch_query_docs` Copy Section

Use this tool with one or more docset_id values returned by algolia_docsearch_resolve_docset. Pass several IDs when the question covers more than one product.

Security and service limits Copy Chapter

Connect only to the HTTPS endpoint shown on this page. Don't add Algolia credentials to the MCP configuration. Send documentation questions, not secrets or confidential data, to the hosted service.

DocSearch MCP searches public content and returns external documentation to your client. Review generated answers and commands before you use them.

:::note[Service terms]

Algolia DocSearch MCP is a free service and is provided by Algolia "AS IS" and "AS AVAILABLE" without warranty of any kind. Algolia may suspend, modify, or discontinue the service at any time at its sole discretion. Algolia disclaims all obligation and liability arising from or related to your use of DocSearch MCP. You must comply with all applicable laws and government regulations when you use the service.

:::

Next steps Copy Chapter

• Install DocSearch MCP
• Use DocSearch MCP

Packages Website Docs Packages Overview (`packages/website/docs/packages/overview.mdx`) Copy Section

title: DocSearch packages Copy Chapter

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

DocSearch v5 provides keyword search, AI answers powered by Agent Studio, and lower-level packages for custom integrations.

Start with @docsearch/js for a browser integration or @docsearch/react for a React application. Both packages support the same keyword search options.

Choose a package Copy Chapter

If your Docusaurus site uses the DocSearch adapter, follow the Docusaurus adapter guide.

Choose a search experience Copy Chapter

Keyword search Copy Section

Use keyword search when you only need results from Algolia indices. It has no Ask AI runtime.

• JavaScript: import @docsearch/js/docsearch.
• React: render DocSearch from @docsearch/react.

Keyword search and Ask AI Copy Section

Use the AI-capable integration when you have an Agent Studio assistant.

• JavaScript: use the default @docsearch/js export.
• React: render DocSearchAI from @docsearch/react.

Create and configure the assistant before adding it to DocSearch. See Get started with Agent Studio.

Composable and hybrid experiences Copy Section

Use the Composable API to control the provider, button, and modal separately. Use hybrid mode to combine the modal with the AI Sidepanel.

For an existing v4 integration, read Migrate from v4 and v5 breaking changes.

Packages Website Docs Packages Core Overview (`packages/website/docs/packages/core/overview.mdx`) Copy Section

title: Core package Copy Chapter

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

@docsearch/core provides the React state shared by DocSearch views. It owns open and close state, keyboard events, theme selection, lifecycle callbacks, initial queries, and imperative controls. It doesn't render a search interface by itself.

Install Copy Chapter

npm install @docsearch/core@^5

yarn add @docsearch/core@^5

pnpm add @docsearch/core@^5

bun add @docsearch/core@^5

Packages such as @docsearch/modal and @docsearch/sidepanel consume this provider. For component composition instructions, see the Composable API guide.

Configure shared behavior Copy Chapter

import { DocSearch } from '@docsearch/core';

export function SearchState({ children }: { children: React.ReactNode }) {
  return (
    <DocSearch
      theme="dark"
      initialQuery="authentication"
      keyboardShortcuts={{
        'Ctrl/Cmd+K': true,
        '/': false,
        'Ctrl/Cmd+I': true,
      }}
      onReady={() => track('docsearch_ready')}
      onOpen={() => track('search_opened')}
      onClose={() => track('search_closed')}
      onSidepanelOpen={() => track('assistant_opened')}
      onSidepanelClose={() => track('assistant_closed')}
    >
      {children}
    </DocSearch>
  );
}

The default shortcuts enable Control/Command+K, /, and Control/Command+I. Slash doesn't open the modal while focus is in an input, select, textarea, or editable element.

Use a ref Copy Chapter

import { DocSearch, type DocSearchRef } from '@docsearch/core';
import { useRef } from 'react';

export function SearchState({ children }: { children: React.ReactNode }) {
  const ref = useRef<DocSearchRef>(null);

  return (
    <>
      <button type="button" onClick={() => ref.current?.open()}>
        Open search
      </button>
      <DocSearch ref={ref}>{children}</DocSearch>
    </>
  );
}

The ref can open and close registered views and report their state. See the core API reference. For interactions between views, see Hybrid Mode.

Read provider state Copy Chapter

Call useDocSearch only beneath DocSearch. The hook throws outside the provider.

import { useDocSearch } from '@docsearch/core';

export function SearchStatus() {
  const { docsearchState, openModal, closeModal } = useDocSearch();

  return (
    <button
      type="button"
      onClick={docsearchState === 'ready' ? openModal : closeModal}
    >
      {docsearchState === 'ready' ? 'Open search' : 'Close search'}
    </button>
  );
}

Use the higher-level modal and Sidepanel packages for their standard triggers. Read context directly when your interface needs custom controls.

Packages Website Docs Packages Docusaurus Adapter Getting Started (`packages/website/docs/packages/docusaurus-adapter/getting-started.mdx`) Copy Section

title: Docusaurus adapter Copy Chapter

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

Use @docsearch/docusaurus-adapter to add keyword search, a search results page, Ask AI, and an Ask AI Sidepanel to Docusaurus.

Before you start Copy Chapter

Collect these values:

• An Algolia application ID.
• A Search API key with access to your DocSearch indices.
• At least one DocSearch index name.
• An Agent Studio assistant ID if you want Ask AI or the Sidepanel. Follow Get started with Agent Studio to create one.

Use Node.js 20 or later, Docusaurus 3.10.2 or later in the Docusaurus 3 release line, and React 18 or 19.

Install the adapter Copy Chapter

Install @docsearch/docusaurus-adapter@^5:

npm install @docsearch/docusaurus-adapter@^5

yarn add @docsearch/docusaurus-adapter@^5

pnpm add @docsearch/docusaurus-adapter@^5

bun add @docsearch/docusaurus-adapter@^5

Keep @docusaurus/preset-classic. Don't add @docusaurus/theme-search-algolia as another search integration.

Configure keyword search Copy Chapter

Add the adapter to plugins. Configure it under themeConfig.docsearch:

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APPLICATION_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [{ name: 'YOUR_INDEX_NAME' }],
    },
  },
};

indices is required and must contain at least one index. Use an object to set search parameters for one index:

indices: [
  {
    name: 'docs',
    searchParameters: {
      facetFilters: ['language:en'],
      attributesToRetrieve: [
        'content',
        'hierarchy',
        'type',
        'url',
        'version',
      ],
    },
  },
],

Start Docusaurus and open the search modal. The adapter also creates /search and links to it from the modal. Change or disable that route with searchPage.

Add Ask AI Copy Chapter

Set askAi to an object with your Agent Studio assistant ID:

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APPLICATION_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [{ name: 'YOUR_INDEX_NAME' }],
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
      },
    },
  },
};

The adapter uses Agent Studio for Ask AI. Pass an object, not an assistant ID string. It reuses the root appId, apiKey, and first keyword index unless you configure dynamic Agent Studio indices.

Add the Sidepanel Copy Chapter

Set sidePanel at the root of docsearch. You must also configure askAi:

docsearch: {
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: [{ name: 'YOUR_INDEX_NAME' }],
  askAi: {
    assistantId: 'YOUR_ASSISTANT_ID',
  },
  sidePanel: true,
},

Pass an object instead of true to configure its placement, width, questions, translations, memory, or indices. The modal and Sidepanel share the DocSearch provider. Review hybrid mode for their responsive behavior.

Next steps Copy Chapter

• Review every adapter option in the configuration reference.
• Follow Migrate from v4 if your site uses themeConfig.algolia, indexName, root searchParameters, or askAi.sidePanel.
• Review the package-level DocSearch v4 migration guide.

Packages Website Docs Packages Js Getting Started (`packages/website/docs/packages/js/getting-started.mdx`) Copy Section

title: JS package Copy Chapter

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

Use @docsearch/js to render DocSearch into an HTML element. The default entry includes keyword search and Ask AI. A separate entry includes keyword search only.

Before you start Copy Chapter

Collect your Algolia application ID, Search API key, and index name. To add Ask AI, also create an assistant in Agent Studio and copy its assistant ID.

Install the packages Copy Chapter

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

Add a container where you want the search button:

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

Pass a container element or a selector that matches one. Don't pass an input; DocSearch renders the search button and input.

Add keyword search and Ask AI Copy Chapter

Import the default entry and provide an askAi configuration:

import docsearch from '@docsearch/js';

import '@docsearch/css';

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: {
    assistantId: 'YOUR_ASSISTANT_ID',
  },
});

The default entry bundles both experiences. askAi accepts an assistant ID string or a configuration object. See the JavaScript API reference.

Add keyword search only Copy Chapter

Import the /docsearch entry to exclude Ask AI code:

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

import '@docsearch/css';

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
});

Load DocSearch from a CDN Copy Chapter

Load the complete stylesheet and one JavaScript bundle. Both UMD bundles expose window.docsearch.

Keyword search and Ask AI Copy Section

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@^5/dist/umd/index.js"></script>
<script>
  window.docsearch({
    container: '#docsearch',
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indices: ['YOUR_INDEX_NAME'],
    askAi: {
      assistantId: 'YOUR_ASSISTANT_ID',
    },
  });
</script>

Keyword search only Copy Section

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@^5/dist/umd/docsearch.js"></script>
<script>
  window.docsearch({
    container: '#docsearch',
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indices: ['YOUR_INDEX_NAME'],
  });
</script>

Don't load both UMD bundles on the same page. The second bundle replaces the same window.docsearch global.

Control the instance Copy Chapter

docsearch() returns a DocSearchInstance:

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'],
  askAi: 'YOUR_ASSISTANT_ID',
});

search.open();
search.close();
search.openAskAi({ query: 'How do I configure search?' });

// Unmount DocSearch when your application removes this view.
search.destroy();

Use openAskAi() only with the default AI-capable entry.

Next steps Copy Chapter

• Review every option in the JavaScript API reference.
• Add multiple indices, facets, or result badges in the React examples. The configuration options also apply to JavaScript.
• Customize the design in Styling.
• Combine the modal and Sidepanel in hybrid mode.

Packages Website Docs Packages Modal Overview (`packages/website/docs/packages/modal/overview.mdx`) Copy Section

title: Modal package Copy Chapter

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

@docsearch/modal provides the DocSearch search button, keyword-search modal, and Agent Studio-enabled modal for React. Render these components inside the DocSearch provider from @docsearch/core.

For the complete component workflow, see the Composable API guide.

Install Copy Chapter

npm install @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

yarn add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

pnpm add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

bun add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

Add keyword search Copy Chapter

Import the main stylesheet once, near your application entry point.

import { DocSearch } from '@docsearch/core';
import { DocSearchButton, DocSearchModal } from '@docsearch/modal';

import '@docsearch/css';

export function Search() {
  return (
    <DocSearch>
      <DocSearchButton />
      <DocSearchModal
        appId="YOUR_APPLICATION_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indices={['YOUR_INDEX_NAME']}
      />
    </DocSearch>
  );
}

Use a search-only API key. Don't expose an Algolia Admin API key in browser code.

Add Agent Studio Copy Chapter

In v5, Ask AI uses Agent Studio. Pass an Agent Studio agent ID through askAi. There's no agentStudio boolean in the v5 API.

import { DocSearch } from '@docsearch/core';
import { DocSearchAskAiModal, DocSearchButton } from '@docsearch/modal';

import '@docsearch/css';

export function Search() {
  return (
    <DocSearch>
      <DocSearchButton />
      <DocSearchAskAiModal
        appId="YOUR_APPLICATION_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indices={['YOUR_INDEX_NAME']}
        askAi="YOUR_AGENT_ID"
      />
    </DocSearch>
  );
}

The askAi object also supports custom tools, conversation memory, and dynamic indices. See the DocSearchAskAiModal API.

Set provider options Copy Chapter

The modal package reads theme, keyboard shortcut, and lifecycle state from DocSearch.

<DocSearch
  theme="dark"
  keyboardShortcuts={{ 'Ctrl/Cmd+K': true, '/': false }}
  onOpen={() => track('search_opened')}
  onClose={() => track('search_closed')}
>
  <DocSearchButton />
  <DocSearchModal
    appId="YOUR_APPLICATION_ID"
    apiKey="YOUR_SEARCH_API_KEY"
    indices={['YOUR_INDEX_NAME']}
  />
</DocSearch>

See the @docsearch/core API for provider props and refs.

Load smaller entry points Copy Chapter

The package exposes component-specific entry points for code splitting:

import { DocSearchAskAiModal } from '@docsearch/modal/askai';
import { DocSearchButton } from '@docsearch/modal/button';
import { DocSearchModal } from '@docsearch/modal/modal';

See the modal API reference for all exports and props.

Packages Website Docs Packages React Getting Started (`packages/website/docs/packages/react/getting-started.mdx`) Copy Section

title: React package Copy Chapter

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

@docsearch/react exports separate components for keyword search and Ask AI. Choose the component that matches your application.

Before you start Copy Chapter

Collect your Algolia application ID, Search API key, and index name. To add Ask AI, create an assistant in Agent Studio and copy its assistant ID.

Install the packages Copy Chapter

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

The package supports React and React DOM versions from 16.8 through 19.

Add keyword search Copy Chapter

Render DocSearch when your site only needs keyword results:

import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

export function Search() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['YOUR_INDEX_NAME']}
    />
  );
}

DocSearch doesn't include the Ask AI experience.

Add keyword search and Ask AI Copy Chapter

Render DocSearchAI and pass the Agent Studio assistant:

import { DocSearchAI } from '@docsearch/react';

import '@docsearch/css';

export function Search() {
  return (
    <DocSearchAI
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['YOUR_INDEX_NAME']}
      askAi={{
        assistantId: 'YOUR_ASSISTANT_ID',
      }}
    />
  );
}

askAi also accepts the assistant ID as a string. Use the object form for Agent Studio search parameters, dynamic indices, tools, memory, and prompt suggestions.

Control DocSearch with a ref Copy Chapter

Both components forward a DocSearchRef:

import { useRef } from 'react';
import { DocSearchAI, type DocSearchRef } from '@docsearch/react';

export function Search() {
  const searchRef = useRef<DocSearchRef>(null);

  return (
    <>
      <button
        type="button"
        onClick={() =>
          searchRef.current?.openAskAi({
            query: 'How do I configure search?',
          })
        }
      >
        Ask about setup
      </button>
      <DocSearchAI
        ref={searchRef}
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indices={['YOUR_INDEX_NAME']}
        askAi="YOUR_ASSISTANT_ID"
      />
    </>
  );
}

Use open() and close() for keyword search. Sidepanel methods become useful when you register a Sidepanel through hybrid mode.

Next steps Copy Chapter

• Review every component option in the React API reference.
• Start from the React examples for indices, facets, badges, templates, and refs.
• Use the Composable API for separate provider, button, and modal components.
• Customize the design in Styling.
• For Docusaurus, follow the Docusaurus adapter guide.

Packages Website Docs Packages Sidepanel Js Getting Started (`packages/website/docs/packages/sidepanel-js/getting-started.mdx`) Copy Section

title: Sidepanel JS package Copy Chapter

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

@docsearch/sidepanel-js mounts the Agent Studio Sidepanel into an existing HTML element. It bundles its rendering dependencies and returns an imperative instance.

Install Copy Chapter

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

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

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

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

Add a container to your page:

<div id="docsearch-sidepanel"></div>

Mount the Sidepanel and retain the returned instance:

import sidepanel from '@docsearch/sidepanel-js';

import '@docsearch/css';
import '@docsearch/css/dist/sidepanel.css';

const assistant = sidepanel({
  container: '#docsearch-sidepanel',
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  agentId: 'YOUR_AGENT_ID',
  onReady() {
    console.info('DocSearch sidepanel is ready');
  },
});

Use a search-only API key. The agentId is an Agent Studio agent ID.

Open with a question Copy Chapter

Pass an initial message to open:

assistant.open({
  query: 'How do I configure a search-only API key?',
});

Call assistant.destroy() before removing the container or remounting another Sidepanel in it.

Load from a CDN Copy Chapter

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/style.css"
/>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/sidepanel.css"
/>

<div id="docsearch-sidepanel"></div>

<script src="https://cdn.jsdelivr.net/npm/@docsearch/sidepanel-js@^5/dist/umd/index.js"></script>
<script>
  const assistant = docsearchSidepanel({
    container: '#docsearch-sidepanel',
    appId: 'YOUR_APPLICATION_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    agentId: 'YOUR_AGENT_ID',
  });
</script>

See the JavaScript Sidepanel API for configuration, Agent Studio options, callbacks, and instance methods.

Packages Website Docs Packages Sidepanel Getting Started (`packages/website/docs/packages/sidepanel/getting-started.mdx`) Copy Section

title: Sidepanel package Copy Chapter

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

@docsearch/sidepanel provides composable React components for an Agent Studio chat panel.

Install Copy Chapter

npm install @docsearch/core@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

yarn add @docsearch/core@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

pnpm add @docsearch/core@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

bun add @docsearch/core@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

Render the Sidepanel Copy Chapter

Import both the main DocSearch stylesheet and the Sidepanel stylesheet.

import { DocSearch } from '@docsearch/core';
import { Sidepanel, SidepanelButton } from '@docsearch/sidepanel';

import '@docsearch/css';
import '@docsearch/css/dist/sidepanel.css';

export function HelpAssistant() {
  return (
    <DocSearch>
      <SidepanelButton />
      <Sidepanel
        appId="YOUR_APPLICATION_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        agentId="YOUR_AGENT_ID"
      />
    </DocSearch>
  );
}

Use a search-only API key. The agentId is an Agent Studio agent ID. V5 doesn't provide the legacy Ask AI backend or an agentStudio switch.

The default button and panel float over the page. Press Control+I or Command+I to toggle the panel, and press Escape to close it.

Configure the provider Copy Chapter

Set the theme and lifecycle callbacks on DocSearch.

<DocSearch
  theme="dark"
  keyboardShortcuts={{ 'Ctrl/Cmd+I': true }}
  onSidepanelOpen={() => track('assistant_opened')}
  onSidepanelClose={() => track('assistant_closed')}
>
  <SidepanelButton variant="inline" />
  <Sidepanel
    appId="YOUR_APPLICATION_ID"
    apiKey="YOUR_SEARCH_API_KEY"
    agentId="YOUR_AGENT_ID"
  />
</DocSearch>

Continue with advanced use cases or review the Sidepanel API. For a combined search and assistant experience, see Hybrid Mode.

Packages Website Docs Api (`packages/website/docs/api.mdx`) Copy Section

title: API references Copy Chapter

Choose the reference for the package in your application:

• @docsearch/js API
• @docsearch/react API
• @docsearch/modal API
• @docsearch/sidepanel API
• @docsearch/sidepanel-js API
• @docsearch/core API
• Docusaurus adapter configuration

For an end-to-end example, start with the package overview.

`container` Copy Chapter

See the @docsearch/js API for the JavaScript container option.

Translations Copy Chapter

See the React API for the shared translation structure.

`askAi` Copy Chapter

See Get started with Agent Studio for AI configuration.

Packages Website Docs Composable Api (`packages/website/docs/composable-api.mdx`) Copy Section

title: Composable API Copy Chapter

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

The composable API gives you control over where DocSearch renders, when its modal code loads, and how the rest of your application opens or closes it.

Use this API in React applications. For the connected component reference, see the modal package overview.

Choose a modal Copy Chapter

DocSearch v5 provides two modal components. Render one modal for each DocSearch provider.

DocSearchAskAiModal includes keyword search. Don't render both modal components to add Ask AI.

The composable components come from three packages:

• @docsearch/core provides DocSearch, shared state, keyboard handling, and the imperative ref.
• @docsearch/modal provides the provider-connected button and modal components.
• @docsearch/css provides the styles.

Install the packages Copy Chapter

Install matching v5 versions of the DocSearch packages:

npm install @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

yarn add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

pnpm add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

bun add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/css@^5

Add keyword search Copy Chapter

Wrap the button and keyword modal in one DocSearch provider. Pass a public search-only API key to the provider; its descendants use these credentials by default.

import { DocSearch } from '@docsearch/core';
import { DocSearchButton, DocSearchModal } from '@docsearch/modal';
import type { JSX } from 'react';

import '@docsearch/css/dist/style.css';

interface KeywordSearchProps {
  appId: string;
  apiKey: string;
  indexName: string;
}

export function KeywordSearch({
  appId,
  apiKey,
  indexName,
}: KeywordSearchProps): JSX.Element {
  return (
    <DocSearch appId={appId} apiKey={apiKey}>
      <DocSearchButton
        translations={{
          buttonText: 'Search docs',
          buttonAriaLabel: 'Search documentation',
        }}
      />
      <DocSearchModal indices={[indexName]} />
    </DocSearch>
  );
}

The provider opens the modal when a user selects the button, presses Ctrl/Command+K, or presses / outside an editable field. Closing the modal returns focus to DocSearchButton.

Add keyword search and Ask AI Copy Chapter

Replace DocSearchModal with DocSearchAskAiModal. Create the assistant in Agent Studio, then configure its ID on the provider.

import { DocSearch } from '@docsearch/core';
import { DocSearchAskAiModal, DocSearchButton } from '@docsearch/modal';
import type { JSX } from 'react';

import '@docsearch/css/dist/style.css';

interface SearchWithAskAiProps {
  appId: string;
  apiKey: string;
  indexName: string;
  agentId: string;
}

export function SearchWithAskAi({
  appId,
  apiKey,
  indexName,
  agentId,
}: SearchWithAskAiProps): JSX.Element {
  return (
    <DocSearch appId={appId} apiKey={apiKey}>
      <DocSearchButton />
      <DocSearchAskAiModal
        indices={[indexName]}
        askAi={agentId}
      />
    </DocSearch>
  );
}

The askAi prop accepts an assistant ID string or an object with agentId. Use the object form when you need options such as indices, searchParameters, suggestedQuestions, promptSuggestions, tools, or memory. Set appId and apiKey on an individual modal or Sidepanel only when they must override the provider's defaults.

Understand the shared state Copy Chapter

DocSearch holds one state value and shares it with its descendants:

The connected components manage these transitions for you:

• DocSearchButton calls its own onClick handler, then opens keyword search.
• Each modal registers itself with the provider and renders in a React portal only while a modal state is active.
• DocSearchModal reads the provider's initial query and close action.
• DocSearchAskAiModal also reads and updates the Ask AI state.

Use useDocSearch in a component under the provider when your application needs declarative access to this state.

import { useDocSearch } from '@docsearch/core';
import type { JSX } from 'react';

export function SearchControls(): JSX.Element {
  const { closeModal, docsearchState, openModal, onAskAiToggle } =
    useDocSearch();

  return (
    <div>
      <span>Search state: {docsearchState}</span>
      <button type="button" onClick={openModal}>
        Open search
      </button>
      <button type="button" onClick={() => onAskAiToggle(true)}>
        Open Ask AI
      </button>
      <button type="button" onClick={closeModal}>
        Close search
      </button>
    </div>
  );
}

Only call onAskAiToggle(true) when the provider contains DocSearchAskAiModal or a compatible Ask AI view.

Control DocSearch with a ref Copy Chapter

Attach a DocSearchRef to the provider when non-React code or a parent component must control DocSearch.

import { DocSearch, type DocSearchRef } from '@docsearch/core';
import { DocSearchAskAiModal, DocSearchButton } from '@docsearch/modal';
import { useRef, type JSX } from 'react';

interface ControlledSearchProps {
  appId: string;
  apiKey: string;
  indexName: string;
  agentId: string;
  onReady?: () => void;
  onOpen?: () => void;
  onClose?: () => void;
}

export function ControlledSearch(props: ControlledSearchProps): JSX.Element {
  const searchRef = useRef<DocSearchRef>(null);

  return (
    <DocSearch
      ref={searchRef}
      onReady={props.onReady}
      onOpen={props.onOpen}
      onClose={props.onClose}
    >
      <DocSearchButton />
      <button
        type="button"
        onClick={() =>
          searchRef.current?.openAskAi({
            query: 'How do I configure DocSearch?',
          })
        }
      >
        Ask a question
      </button>
      <DocSearchAskAiModal
        appId={props.appId}
        apiKey={props.apiKey}
        indices={[props.indexName]}
        askAi={props.agentId}
      />
    </DocSearch>
  );
}

The ref exposes these methods and read-only values. initialMessage has a required query and optional messageId and suggestedQuestionId fields.

The provider accepts onReady, onOpen, onClose, onSidepanelOpen, and onSidepanelClose. onReady runs after mount. The other callbacks run once when their corresponding view changes state, not every time React renders.

`open` Copy Section

type: () => void

Opens keyword search.

`close` Copy Section

type: () => void

Returns the provider to ready.

`openAskAi` Copy Section

type: (initialMessage?: InitialAskAiMessage) => void

Opens Ask AI in a registered Sidepanel on desktop, or in the modal otherwise.

`openSidepanel` Copy Section

type: (initialMessage?: InitialAskAiMessage) => void

Opens a registered Sidepanel. It does nothing when no Sidepanel is registered.

`isReady` Copy Section

type: readonly boolean

Reports whether the provider is mounted.

`isOpen` Copy Section

type: readonly boolean

Reports whether a modal view is open.

`isSidepanelOpen` Copy Section

type: readonly boolean

Reports whether the Sidepanel is open.

`isSidepanelSupported` Copy Section

type: readonly boolean

Reports whether desktop hybrid mode is available.

Load the modal on demand Copy Chapter

Import the button eagerly and split the larger modal into another JavaScript chunk. The following Ask AI example preloads that chunk on hover, focus, or touch, then renders it only after the provider opens a modal state.

/* Detailed source-code truncated for AI context efficiency. */

Render the provider and connected components only in the browser. The modal wrappers read document.body and window.scrollY when they render.

Use the exact entry points Copy Chapter

Use the package root for convenience or a subpath to keep eager bundles focused.

The lower-level React entry points are @docsearch/react/button, @docsearch/react/modal, and @docsearch/react/askaiModal. They don't connect themselves to the composable provider. Use them only when you intend to manage portal rendering, refs, initialScrollY, close behavior, and Ask AI state yourself.

Load the styles Copy Chapter

For either complete modal, import the combined stylesheet once:

import '@docsearch/css/dist/style.css';

The combined stylesheet contains variables, button styles, keyword modal styles, and Ask AI modal styles. It doesn't contain Sidepanel styles.

For a keyword-only CSS bundle, import the layers in this order:

import '@docsearch/css/dist/_variables.css';
import '@docsearch/css/dist/button.css';
import '@docsearch/css/dist/modal.css';

Add @docsearch/css/dist/_askai.css when you use DocSearchAskAiModal. Bundlers can also load the same files through @docsearch/react/style, @docsearch/react/style/button, @docsearch/react/style/modal, @docsearch/react/style/askai, and @docsearch/react/style/variables.

API summary Copy Chapter

DocSearchButton accepts native React button props and translations. The connected wrapper doesn't accept theme or keyboardShortcuts; set those on DocSearch.

Both connected modal wrappers accept the corresponding low-level modal options, except the state and lifecycle fields supplied by the provider. Explicit appId and apiKey props override their respective provider values. Consult the modal API before adding options.

Packages Website Docs Crawler Configuration Visual (`packages/website/docs/crawler-configuration-visual.mdx`) Copy Section

title: Crawler interface Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

Use the Algolia Crawler interface to manage crawl settings and monitor indexing. These settings are separate from your installed DocSearch frontend package version.

DocSearch tab Copy Chapter

The Crawler UI now includes a dedicated DocSearch tab. This tab provides everything you need to implement DocSearch on your site, including:

• Implementation code: Starter snippets for integrating DocSearch into your frontend. For v5, compare the snippet with the current package guide.
• API keys: Your unique Application ID and Search API Key for connecting to your Algolia index.
• Documentation links: Access to review your records, explore documentation, and join the support Discord.

Trigger a new crawl Copy Chapter

Head over to the Overview section to start, restart or pause your crawls and view a real-time summary.

Monitor your crawls Copy Chapter

The Monitoring section helps you find crawl errors or improve your search results.

Update your config Copy Chapter

You can update your crawler configuration in two ways:

Visual configuration: Edit common options without writing code in the visual configuration interface.

Code editor: For advanced configuration, use the live code editor to modify your configuration and test URLs with the URL tester.

URL tester Copy Chapter

From the editor, you can use the URL tester to debug selectors or see how the crawler interprets your site.

Suggestions Copy Chapter

The Suggestions section in the Crawler UI provides actionable feedback to help you improve your crawl and data extraction. After each crawl, you'll see recommendations for:

• Fixing redirect or domain issues
• Addressing ignored or failed URLs
• Adding missing sitemaps

Each suggestion includes a description, a solution, and links to relevant documentation or monitoring tools.

Packages Website Docs Crawler (`packages/website/docs/crawler.mdx`) Copy Section

title: DocSearch x Algolia Crawler Copy Chapter

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

Use this page to resolve common crawler questions. If you need more help, contact us on Discord or through Algolia support.

For more troubleshooting guidance, read the Crawler FAQ:

• One of my pages wasn't crawled
• Why are my pages skipped?

For questions related to the DocSearch program, please see our DocSearch program FAQ.

How often will you crawl my website? Copy Chapter

Crawls are scheduled at a random time once a week. You can configure this schedule from the config file or trigger one manually from the Crawler interface.

Why do I have duplicate content in my results? Copy Chapter

This can happen when you have more than one URL pointing to the same content, for example with ./docs, ./docs/ and ./docs/index.html.

Configure canonical URLs on your website. For more information, read Google's Consolidate duplicate URLs guide.

Use exclusionPatterns to exclude duplicate URL patterns.

Are the [`docsearch-scraper`][9] and [`docsearch-configs`][10] repositories still maintained? Copy Chapter

The legacy scraper infrastructure is deprecated. You can still run a legacy scraper instance and use its index with the historical DocSearch v3 UI. For current frontend integrations, choose a DocSearch v5 package. The scraper or crawler version doesn't determine the frontend package version.

How do I migrate? Copy Chapter

Every owner should have received a migration email from Algolia with the details. If you were not part of the previous index owners, or the maintainer has changed, you can request access via our support page.

Use the migration email to complete these steps:

• Join the Algolia application with the invite included in the email
• Update your frontend integration with the credentials received in the email. For v5, follow the JavaScript or React guide.

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

<DocSearch
  appId="YOUR_NEW_ALGOLIA_APP_ID"
  apiKey="YOUR_NEW_ALGOLIA_SEARCH_API_KEY"
  indices={['YOUR_INDEX_NAME']} // The index name doesn't change.
/>

docsearch({
  container: '#docsearch',
  appId: 'YOUR_NEW_ALGOLIA_APP_ID',
  apiKey: 'YOUR_NEW_ALGOLIA_SEARCH_API_KEY',
  indices: ['YOUR_INDEX_NAME'], // The index name doesn't change.
});

What should I do with my legacy config and credentials? Copy Chapter

Use the credentials for your current Algolia application. Don't use legacy credentials for new frontend integrations.

You should use the dedicated web interface to make any changes to your index.

Why do I see two Algolia apps in my dashboard? Copy Chapter

We did not remove access to the legacy DocSearch application (BH4D9OD16A) to give you the time to get familiar with our new infrastructure. BH4D9OD16A will remain available until the migration has been completed for all the DocSearch users.

Search yields no results Copy Chapter

If your search does not yield any results, but there is no error in your browser developer tools, there might be an issue with your index.

Check the following settings:

1. Confirm that your crawler configuration matches your website structure.

   Use a configuration template for your website generator as a starting point. Test your selectors with the URL tester.

2. Confirm that your index settings are current. If they aren't, the search preview displays a banner.

   The crawler applies index settings only when it creates an index, which keeps the Algolia dashboard as the source of truth. If you changed your configuration significantly or moved to a different website generator, delete the index from the Algolia dashboard before starting a new crawl.

Can I delete my crawler? Copy Chapter

Don't delete the default crawler associated with your DocSearch application. Creating a replacement might not preserve the program configuration.

What if I delete my DocSearch Crawler? Copy Chapter

Contact us on Discord or email us at the address below.

Can I use the crawler on password-protected sites? Copy Chapter

The crawler included with DocSearch applications can't access password-protected sites that require a login. To crawl these sites, choose an Algolia plan and add a crawler. Pay-as-you-go plans include a crawler, but the free tier has usage limits.

Links related to the migration Copy Chapter

• Docusaurus blog post
• Algolia Dev chat 11-23-2021

Packages Website Docs Create Crawler (`packages/website/docs/create-crawler.mdx`) Copy Section

title: Create a new crawler Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

Create a new crawler

:::info

DocSearch apps created after July 2, 2024 can use the Algolia Crawler UI to set up and manage crawls. This guide covers adding your domain, verifying ownership, creating a crawler, and running your first test crawl. Open the Crawler UI at dashboard.algolia.com/crawler.

If you signed up before July 2, 2024, you can still use the Crawler UI, but creating and managing a crawler is more streamlined for users who joined after that date.

Learn more about the Crawler interface.

:::

Add domains Copy Chapter

1. Sign in to the Algolia dashboard.
2. In the left sidebar, select Data sources.
3. Select Crawler:
   • Click Add your domain and enter the domains or subdomains you want to crawl (e.g., example.com, www.example.com).
   • If you’ve already added a domain, click the Domains tab.
4. Click Add domain.

Note: Verify your domain within 7 days of adding it. The DocSearch team must also approve the domain before you can crawl it.

Verify your domain Copy Chapter

You must verify ownership of each domain you want to crawl. The default method is email verification, but you can also use a meta tag, HTML file, robots.txt, or DNS record.

Meta tag Copy Section

1. In the Meta tag tab, click Copy to copy the verification tag.
2. Add the tag to your site's <head> section.
3. Publish your site and click Verify now in the Crawler dashboard.

HTML file Copy Section

1. In the HTML file tab, click Copy to copy the verification file content.
2. Save it as a new HTML file and upload it to your web server.
3. Add the file’s URL in the dashboard and click Verify now.

robots.txt Copy Section

1. In the Robots.txt tab, click Copy to copy the verification code.
2. Paste it into your site's robots.txt file.
3. Publish and click Verify now.

DNS Copy Section

1. In the DNS tab, copy the provided DNS TXT record.
2. Add it to your DNS provider’s settings.
3. Click Verify now after the record propagates (may take up to 72 hours).

Create a new crawler Copy Chapter

After you verify your domain and the DocSearch team approves it:

1. Go to the Crawler page in the dashboard.
2. Click New Crawler and fill in:
   • Crawler name (descriptive)
   • App ID (your Algolia application ID)
   • Start URL (usually your home page)
   • Crawler template (choose a template or default)
3. Click Create to finish and run a test crawl.

Run the test crawl Copy Chapter

The initial crawl visits up to 100 URLs to test access and extraction. Monitor its progress on the Overview page. After it finishes, review the extracted records in the Algolia dashboard.

Creating a crawler doesn't install or select a DocSearch frontend version. After indexing, choose a DocSearch v5 package or framework integration.

Next steps Copy Chapter

• Edit your crawler configuration for scheduled crawls, inclusion/exclusion rules, and extraction settings.
• Use the Crawler’s suggestions for further optimization.
• For more details, see the Algolia Crawler documentation.

Packages Website Docs Docsearch Program (`packages/website/docs/docsearch-program.md`) Copy Section

title: DocSearch program Copy Chapter

Use this page to learn about the DocSearch program. If you need more help, contact us on Discord or through Algolia support.

For questions about the DocSearch crawler, see the Crawler FAQ.

What do I need to install on my side? Copy Chapter

After your content is indexed, add a DocSearch v5 frontend package with the application ID, Search API key, and index name from your Algolia application.

DocSearch uses the Algolia Crawler to index your content. Use the Crawler interface to create, monitor, edit, and start crawlers. For crawler questions, see the Crawler FAQ. Crawler configuration and frontend package versions are independent.

How much does it cost? Copy Chapter

The DocSearch program is free.

Search infrastructure can be costly for open source projects, so the DocSearch program is free. In exchange, keep the "Search by Algolia" logo next to the search results.

If you can't display the logo, create an Algolia account and run DocSearch on your own. Depending on the size of your documentation, you might need a paid plan. Free plans can hold up to 10,000 records.

What data are you collecting? Copy Chapter

We extract data from your website markup and store it in a custom JSON format in your Algolia DocSearch index. The selectors in your crawler configuration determine what data to extract.

As the website owner, you can access your Algolia application to review indexed data, analyze anonymized searches, and manage your team.

Where is my data hosted? Copy Chapter

We host DocSearch data on Algolia servers with replicas around the world. For more information, see the Algolia infrastructure documentation and privacy policy.

How do I upgrade my DocSearch app? Copy Chapter

Choose an option based on your goal.

Upgrade #1: I want a specific feature, like Rules, added to my existing DocSearch application Copy Section

Contact Algolia support to discuss your requirements.

Upgrade #2: I want to remove the Algolia logo Copy Section

Removing the logo makes the project ineligible for the free DocSearch program. Instead, host the open source legacy DocSearch crawler or use an Algolia API client. Both options require a new Algolia application, and usage charges may apply.

Upgrade #3: Algolia is awesome, I want to use it for my whole site Copy Section

Contact the Algolia sales team to choose a plan. After creating your application, adapt a crawler configuration template for the new crawler.

Can I use DocSearch on non-doc pages? Copy Chapter

The free DocSearch program crawls only documentation pages for open source projects and technical blogs. To index other parts of your website, create an Algolia account and choose one of these options:

• Run the DocSearch crawler on your own
• Use a DocSearch frontend package, a supported framework integration, or an Algolia API client

Can you index code samples? Copy Chapter

Yes, but we do not recommend it.

Code samples can help users understand a method, but repeated boilerplate adds noise to search results.

A documentation website I like does not use DocSearch. What can I do? Copy Chapter

If a documentation website does not use DocSearch, file an issue in its repository that explains how DocSearch could help. You can also contact us on Discord.

How did we build this website? Copy Chapter

We built this website with Docusaurus. Endi helped inspire the project. Read our tribute to Endi.

Can I share the `apiKey` in my repo? Copy Chapter

The apiKey from the DocSearch team is a search-only API key, so you can share it publicly and track it in version control. If you run the scraper yourself, create a search-only key and don't share your Admin API key.

Why is the email API key different in the dashboard? Copy Chapter

Every Algolia application has a default "Search API Key" in the dashboard. That key lets you list indices, retrieve settings, and search every index in your application. For DocSearch applications, the acceptance email includes a search-only API key scoped to your DocSearch index. To recover this key, contact Algolia support.

How do I rotate my API keys? Copy Chapter

Contact Algolia support.

Can I have multiple projects under the same Algolia application? Copy Chapter

Use one Algolia application per project. Apply to the DocSearch program for each additional project.

Why? Copy Section

The information of the initially applied project is used everywhere when we deploy your app:

• The scope of your API keys
• The name of your Algolia application/Crawler
• The indices we generate
• The allowed domains of your Crawler

This information helps us scope support requests to the correct project.

Support Copy Chapter

:::caution

Before contacting support, read the relevant documentation.

Here are some links to help you:

• The Algolia Crawler documentation
• The Algolia Crawler FAQ
• The DocSearch FAQ
• The Algolia documentation

Visit Algolia Academy to learn more about Algolia.

:::

Algolia doesn't provide support for the DocSearch UI library, but support is available for these products:

• Contact Algolia support for the Algolia Crawler.
• Contact Algolia support for the Algolia dashboard.

For any issue related to the DocSearch UI library, please open a GitHub issue.

Packages Website Docs Docsearch (`packages/website/docs/docsearch.mdx`) Copy Section

title: Get started with DocSearch Copy Chapter

DocSearch v5 provides separate packages for JavaScript, React, composable interfaces, and framework integrations.

Start with the package overview to choose an integration:

• Use @docsearch/js for a JavaScript application.
• Use @docsearch/react for a React application.
• Use the Docusaurus adapter for a Docusaurus site.
• Use the Composable API to control the React interface.

To upgrade an existing integration, follow Migrating from v4.

Installation Copy Chapter

Install instructions depend on your package. Open the package guide above for commands and required styles.

Packages Website Docs Docusaurus Adapter (`packages/website/docs/docusaurus-adapter.mdx`) Copy Section

title: Docusaurus adapter Copy Chapter

Use @docsearch/docusaurus-adapter to add DocSearch v5 to a Docusaurus site.

• Install the adapter.
• Configure the adapter.
• Migrate a v4 configuration.

Packages Website Docs Examples (`packages/website/docs/examples.mdx`) Copy Section

title: Examples Copy Chapter

Use these guides for production-ready examples:

• React examples
• Composable API
• Hybrid Mode
• Agent Studio tools
• Docusaurus adapter

For JavaScript setup examples, see Get started with @docsearch/js.

Packages Website Docs How Does It Work (`packages/website/docs/how-does-it-work.mdx`) Copy Section

title: How does it work? Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

DocSearch setup has three parts: join the DocSearch program, index your content, and add a frontend package or framework integration.

You apply Copy Chapter

First, confirm that your website qualifies, then apply for DocSearch. The onboarding flow validates your domain against the program requirements.

If automated validation can't determine eligibility, the application might require a manual review.

Index your content Copy Chapter

After approval, create a dedicated crawler in your Algolia application. Its configuration file defines which URLs to crawl, which URLs to ignore, and which selectors extract your content hierarchy.

Run a test crawl, review the extracted records, and configure recurring crawls. Use the Crawler interface to adjust the configuration as your website changes.

With the Crawler, comes a dedicated interface for you to:

• Start, schedule and monitor your crawls
• Edit and test your crawler configuration

With the Algolia application comes access to the dashboard for you to:

• Browse your index and see how your content is indexed
• Review analytics to understand how search performs
• Trials for other Algolia features
• Team management

Add DocSearch to your website Copy Chapter

Choose a DocSearch v5 package or supported framework integration. Configure it with your application ID, Search API key, and index name. The frontend queries the Algolia index and displays the results.

Crawler versions, record schema versions, and frontend package versions are separate. In particular, crawler recordVersion: 'v3' describes the indexed record schema, not the DocSearch UI version. You can upgrade the v5 frontend packages without recreating the crawler. Keep the "Search by Algolia" logo next to your search results.

Packages Website Docs Hybrid Mode (`packages/website/docs/hybrid-mode.mdx`) Copy Section

title: Hybrid mode Copy Chapter

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

Hybrid mode starts in the DocSearch modal, then moves an Ask AI request into the Sidepanel. Users can scan keyword results in a focused overlay and continue an AI conversation beside the page.

The handoff carries the prompt and its identifiers. It doesn't submit the same prompt in both interfaces.

Prerequisites Copy Chapter

Before you add hybrid mode:

• Use matching v5 DocSearch package versions.
• Configure a searchable Algolia index and a public search-only API key.
• Create an assistant in Agent Studio.
• Decide whether you need React, JavaScript, or the DocSearch Docusaurus adapter.

Read the package references for core, modal, Sidepanel, JavaScript, Sidepanel JavaScript, and the Docusaurus adapter when you need options beyond this workflow.

Understand the handoff Copy Chapter

An Ask AI action can come from a typed prompt, a suggested question, a prompt suggestion in keyword results, or a saved conversation.

DocSearch represents the action as an InitialAskAiMessage:

interface InitialAskAiMessage {
  query: string;
  messageId?: string;
  suggestedQuestionId?: string;
}

Preserve the complete object during a manual handoff:

• query becomes the first prompt when the Sidepanel starts a conversation.
• suggestedQuestionId is sent with the prompt so Agent Studio can identify the selected suggestion.
• messageId lets the Sidepanel restore a locally stored conversation. If it can't find that conversation, it starts a new one with query.

Add hybrid mode Copy Chapter

npm install @docsearch/core@^5 @docsearch/modal@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

yarn add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

pnpm add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

bun add @docsearch/core@^5 @docsearch/modal@^5 @docsearch/sidepanel@^5 @docsearch/css@^5

import { DocSearch } from '@docsearch/core';
import { DocSearchAskAiModal, DocSearchButton } from '@docsearch/modal';
import { Sidepanel, SidepanelButton } from '@docsearch/sidepanel';
import type { JSX } from 'react';

import '@docsearch/css/dist/style.css';
import '@docsearch/css/dist/sidepanel.css';

interface HybridSearchProps {
  appId: string;
  apiKey: string;
  keywordIndexName: string;
  agentId: string;
  onReady?: () => void;
  onOpen?: () => void;
  onClose?: () => void;
  onSidepanelOpen?: () => void;
  onSidepanelClose?: () => void;
}

export function HybridSearch({
  appId,
  apiKey,
  keywordIndexName,
  agentId,
  onReady,
  onOpen,
  onClose,
  onSidepanelOpen,
  onSidepanelClose,
}: HybridSearchProps): JSX.Element {
  return (
    <DocSearch
      onReady={onReady}
      onOpen={onOpen}
      onClose={onClose}
      onSidepanelOpen={onSidepanelOpen}
      onSidepanelClose={onSidepanelClose}
    >
      <DocSearchButton />
      <DocSearchAskAiModal
        appId={appId}
        apiKey={apiKey}
        indices={[keywordIndexName]}
        askAi={{ agentId }}
      />

      <SidepanelButton />
      <Sidepanel
        appId={appId}
        apiKey={apiKey}
        agentId={agentId}
      />
    </DocSearch>
  );
}

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

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

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

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

<div id="docsearch"></div>
<div id="docsearch-sidepanel"></div>

import docsearch, { type DocSearchInstance } from '@docsearch/js';
import sidepanel, { type SidepanelInstance } from '@docsearch/sidepanel-js';

import '@docsearch/css/dist/style.css';
import '@docsearch/css/dist/sidepanel.css';

const appId = 'YOUR_APP_ID';
const apiKey = 'YOUR_SEARCH_API_KEY';
const keywordIndexName = 'YOUR_KEYWORD_INDEX_NAME';
const agentId = 'YOUR_AGENT_ID';
const mobileQuery = window.matchMedia('(max-width: 768px)');

let search: DocSearchInstance | undefined;
let panel: SidepanelInstance | undefined;

panel = sidepanel({
  container: '#docsearch-sidepanel',
  appId,
  apiKey,
  agentId,
  onReady: () => {
    document.body.setAttribute('data-sidepanel-ready', '');
  },
  onOpen: () => {
    search?.close();
    document.body.setAttribute('data-sidepanel-open', '');
  },
  onClose: () => {
    document.body.removeAttribute('data-sidepanel-open');
  },
});

search = docsearch({
  container: '#docsearch',
  appId,
  apiKey,
  indices: [keywordIndexName],
  askAi: agentId,
  interceptAskAiEvent: (initialMessage) => {
    if (mobileQuery.matches) {
      return false;
    }

    search?.close();
    panel?.open(initialMessage);
    return true;
  },
  onReady: () => {
    document.body.setAttribute('data-docsearch-ready', '');
  },
  onOpen: () => {
    panel?.close();
    document.body.setAttribute('data-search-open', '');
  },
  onClose: () => {
    document.body.removeAttribute('data-search-open');
  },
});

Add hybrid mode to Docusaurus Copy Chapter

Hybrid mode is supported through @docsearch/docusaurus-adapter. The adapter loads the v5 modal and Sidepanel, connects their state, and applies the mobile behavior described in this guide.

Install the adapter and keep @docusaurus/preset-classic:

npm install @docsearch/docusaurus-adapter@^5

yarn add @docsearch/docusaurus-adapter@^5

pnpm add @docsearch/docusaurus-adapter@^5

bun add @docsearch/docusaurus-adapter@^5

Configure DocSearch under themeConfig.docsearch. Set top-level sidePanel to true or to a Sidepanel options object.

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [{ name: 'YOUR_INDEX_NAME' }],
      askAi: {
        agentId: 'YOUR_AGENT_ID',
      },
      sidePanel: true,
      contextualSearch: true,
      searchPage: { path: 'search' },
    },
  },
};

The adapter requires askAi to be an object with agentId; it doesn't accept the string shorthand in Docusaurus configuration. It also requires askAi whenever sidePanel is set.

Don't put sidePanel inside askAi. Don't configure this adapter under themeConfig.algolia. If you need function-valued custom tools, pass them through a swizzled @theme/SearchBar component because Docusaurus removes functions while serializing theme configuration.

The built-in @docusaurus/theme-search-algolia integration doesn't provide this v5 Sidepanel configuration. Use the DocSearch adapter for this workflow.

Mobile behavior Copy Chapter

The React provider treats viewports that match (max-width: 768px) as mobile. On those viewports, an Ask AI action stays in the modal even when a Sidepanel is registered. This avoids moving the conversation into the desktop Sidepanel layout.

The provider updates this decision on window resize. The Sidepanel also avoids focusing its prompt automatically on mobile because opening the virtual keyboard can disrupt the layout.

The JavaScript packages don't share a provider, so they don't apply the hybrid mobile decision to your interceptor. Add the matchMedia branch shown in the JavaScript example when you want the same behavior.

Load the styles Copy Chapter

Hybrid mode needs both style bundles:

import '@docsearch/css/dist/style.css';
import '@docsearch/css/dist/sidepanel.css';

style.css includes shared variables, the button, keyword modal, and Ask AI modal. sidepanel.css adds the Sidepanel layout and imports the shared variables it needs.

If your bundler resolves the React style entry points, @docsearch/react/style and @docsearch/react/style/sidepanel load the same bundles. Import each bundle once.

Troubleshoot hybrid mode Copy Chapter

Ask AI stays in the modal on desktop Copy Section

Confirm that Sidepanel is mounted under the same DocSearch provider before the Ask AI action. The provider enables automatic handoff only after the Sidepanel registers. Also confirm that the viewport is wider than 768 pixels.

Both the modal and Sidepanel submit the prompt Copy Section

Return true from interceptAskAiEvent after calling panel.open(initialMessage). Returning false or no value tells the modal to continue its default flow.

Mobile users open the Sidepanel Copy Section

In JavaScript integrations, check (max-width: 768px) in the interceptor and return false on a match. React and the Docusaurus adapter already make this decision.

The Sidepanel loses a suggestion or saved conversation Copy Section

Pass the complete initialMessage object to open(). Rebuilding it with only query discards suggestedQuestionId and messageId.

A callback doesn't run during React handoff Copy Section

Expect onSidepanelOpen, not onClose, when React changes directly from the modal to the Sidepanel. Use the shared provider callbacks rather than treating modal close as the handoff signal.

Two JavaScript interfaces remain open Copy Section

Close the search instance in the Sidepanel's onOpen, and close the Sidepanel in the search instance's onOpen. This also covers programmatic calls that bypass the interceptor.

The interface is unstyled Copy Section

Import both style.css and sidepanel.css. Check that your bundler includes CSS imports from dependencies.

Docusaurus rejects the configuration Copy Section

Use themeConfig.docsearch, pass askAi as an object, and put sidePanel beside askAi. Install @docsearch/docusaurus-adapter@^5 instead of configuring hybrid mode through the built-in Algolia theme.

Server rendering fails with `window` or `document` errors Copy Section

Mount the composable React components only in the browser. The Docusaurus adapter handles this boundary and lazy-loads the modal and Sidepanel client-side.

Packages Website Docs Integrations (`packages/website/docs/integrations.md`) Copy Section

title: Supported integrations Copy Chapter

Documentation frameworks can embed DocSearch in the websites they generate. A framework integration configures the frontend; your Algolia Crawler and index remain separate.

Framework integrations Copy Chapter

If you use one of the following tools, follow its documentation to enable DocSearch. Framework documentation can target a different DocSearch frontend release, so check its package compatibility before adopting v5.

• Docusaurus v1 - How to enable search
• Docusaurus v2 and v3 - DocSearch v5 adapter / Using Algolia DocSearch
• VuePress - Algolia Search
• VitePress - Search
• Starlight - Algolia Search
• LaRecipe - Algolia Search
• Smooth DOC - DocSearch
• Docsy - Configure Algolia DocSearch
• Lotus Docs - Enabling the DocSearch Plugin
• Sphinx - Algolia DocSearch for Sphinx

If you maintain a similar tool and want us to add it to the list, open a pull request and contribute to Code Exchange.

Packages Website Docs Manage Your Crawls (`packages/website/docs/manage-your-crawls.mdx`) Copy Section

title: Legacy crawler interface Copy Chapter

:::caution

This crawler interface is deprecated and no longer maintained. It isn't a DocSearch frontend version. For current instructions, use the Crawler interface guide. Open the current interface at dashboard.algolia.com/crawler.

:::

import useBaseUrl from '@docusaurus/useBaseUrl';

DocSearch comes with the Algolia Crawler web interface that allows you to configure how and when your Algolia index will be populated.

Trigger a new crawl Copy Chapter

Head over to the Overview section to start, restart or pause your crawls and view a real-time summary.

Monitor your crawls Copy Chapter

The monitoring section helps you find crawl errors or improve your search results.

Update your config Copy Chapter

The live editor allows you to update your config file and test your URLs (URL tester).

Search preview Copy Chapter

The legacy editor's Search preview tab renders results with the historical DocSearch v3 frontend. This preview doesn't require your website to use that frontend version. For current integrations, see the v5 package guides.

URL tester Copy Chapter

From the editor, your can use the URL tester to debug selectors or how we crawl your website.

Packages Website Docs Migrating From Legacy (`packages/website/docs/migrating-from-legacy.mdx`) Copy Section

title: Migrating from the legacy scraper Copy Chapter

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

Introduction Copy Chapter

This guide covers the historical migration from the self-hosted DocSearch scraper to the Algolia Crawler. It is separate from upgrading the frontend UI. For the current frontend, choose a DocSearch v5 package.

What's new? Copy Chapter

Indexing infrastructure Copy Section

DocSearch indexing now uses the Algolia Crawler. The DocSearch helper extracts records in place of the legacy DocSearch scraper.

You don't need to install local scraper tooling to maintain or update your index.

Use the legacy interface or the current Crawler interface to:

• Start, schedule and monitor your crawls
• Edit your config file from our live editor
• Test results with the historical DocSearch v3 or DocSearch v4 previews

These preview versions don't set the crawler record schema or the frontend package installed on your website. Likewise, crawler recordVersion: 'v3' names a record schema, not DocSearch UI v3.

Algolia application and credentials Copy Section

We've received a lot of requests asking for:

• A way to manage team members
• Browse and see how Algolia records are indexed
• See and subscribe to other Algolia features

These features are available in your Algolia application.

FAQ Copy Chapter

You can find answers related to the DocSearch migration in our Crawler FAQ page.

Useful links Copy Section

• Docusaurus blog post
• Algolia Dev chat 11-23-2021

Config file key mapping Copy Chapter

Below are the keys that can be found in the legacy DocSearch configs and their translation to an Algolia Crawler config. For more detailed information on the Algolia Crawler, see the official documentation.

Packages Website Docs Migrating From V4 (`packages/website/docs/migrating-from-v4.mdx`) Copy Section

title: Migrate from DocSearch v4 Copy Chapter

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

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 packages Copy Chapter

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

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 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 Copy Chapter

JavaScript without Ask AI Copy Section

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:

-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:

-<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 Copy Section

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

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 Copy Section

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

import { DocSearch } from '@docsearch/react';

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

React with Ask AI Copy Section

Replace DocSearch with DocSearchAI:

-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:

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

3. Move Ask AI to Agent Studio Copy Chapter

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.

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:

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` Copy Chapter

indexName and root searchParameters both have been removed in v5.

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 Copy Chapter

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:

<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 Copy Chapter

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

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 Copy Chapter

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 Copy Chapter

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

Packages Website Docs Record Extractor (`packages/website/docs/record-extractor.md`) Copy Section

title: Record Extractor Copy Chapter

Introduction Copy Chapter

:::info

This page documents the helpers.docsearch method. See the Algolia Crawler documentation for information about the Algolia Crawler.

:::

Set the recordExtractor parameter on an action to extract each page. Its function returns the data to index as an array of JSON objects.

The helpers are functions for extracting content and generating Algolia records.

Useful links Copy Section

• Extracting records with the Algolia Crawler
• recordExtractor parameters

Usage Copy Chapter

The most common way to use the DocSearch helper is to return its result to the recordExtractor function.

recordExtractor: ({ helpers }) => {
  return helpers.docsearch({
    recordProps: {
      lvl0: {
        selectors: "header h1",
      },
      lvl1: "article h2",
      lvl2: "article h3",
      lvl3: "article h4",
      lvl4: "article h5",
      lvl5: "article h6",
      content: "main p, main li",
    },
  });
},

Manipulate the DOM with Cheerio Copy Section

The Cheerio instance ($) allows you to manipulate the DOM:

recordExtractor: ({ $, helpers }) => {
  // Removing DOM elements we don't want to crawl
  $(".my-warning-message").remove();

  return helpers.docsearch({
    recordProps: {
      lvl0: {
        selectors: "header h1",
      },
      lvl1: "article h2",
      lvl2: "article h3",
      lvl3: "article h4",
      lvl4: "article h5",
      lvl5: "article h6",
      content: "main p, main li",
    },
  });
},

Provide fallback selectors Copy Section

Fallback selectors can be useful when retrieving content that might not exist in some pages:

recordExtractor: ({ $, helpers }) => {
  return helpers.docsearch({
    recordProps: {
      // `.exists h1` will be selected if `.exists-probably h1` does not exists.
      lvl0: {
        selectors: [".exists-probably h1", ".exists h1"],
      },
      lvl1: "article h2",
      lvl2: "article h3",
      lvl3: "article h4",
      lvl4: "article h5",
      lvl5: "article h6",
      // `.exists p, .exists li` will be selected.
      content: [
        ".does-not-exists p, .does-not-exists li",
        ".exists p, .exists li",
      ],
    },
  });
},

Provide raw text (`defaultValue`) Copy Section

Only the lvl0 and custom variables selectors support this option

You might want to structure your search results differently than your website, or provide a defaultValue to a potentially non-existent selector:

recordExtractor: ({ $, helpers }) => {
  return helpers.docsearch({
    recordProps: {
      lvl0: {
        // It also supports the fallback DOM selectors syntax!
        selectors: ".exists-probably h1",
        defaultValue: "myRawTextIfDoesNotExists",
      },
      lvl1: "article h2",
      lvl2: "article h3",
      lvl3: "article h4",
      lvl4: "article h5",
      lvl5: "article h6",
      content: "main p, main li",
      // The variables below can be used to filter your search
      language: {
        // It also supports the fallback DOM selectors syntax!
        selectors: ".exists-probably .language",
        // Since custom variables are used for filtering, we allow sending
        // multiple raw values
        defaultValue: ["en", "en-US"],
      },
    },
  });
},

Indexing content for faceting Copy Section

These selectors also support defaultValue and fallback selectors

To index content for frontend filters, such as version or language, define custom variables in recordProps. The helper adds them to each matching Algolia record:

recordExtractor: ({ helpers }) => {
  return helpers.docsearch({
    recordProps: {
      lvl0: {
        selectors: "header h1",
      },
      lvl1: "article h2",
      lvl2: "article h3",
      lvl3: "article h4",
      lvl4: "article h5",
      lvl5: "article h6",
      content: "main p, main li",
      // The variables below can be used to filter your search
      foo: ".bar",
      language: {
        // It also supports the fallback DOM selectors syntax!
        selectors: ".does-not-exists",
        // Since custom variables are used for filtering, we allow sending
        // multiple raw values
        defaultValue: ["en", "en-US"],
      },
      version: {
        // You can send raw values without `selectors`
        defaultValue: ["latest", "stable"],
      },
    },
  });
},

The version, language, and foo attributes are then available in your records:

{
  "foo": "valueFromBarSelector",
  "language": ["en", "en-US"],
  "version": ["latest", "stable"]
}

Add every filter attribute to the index's attributesForFaceting, then expose up to five of them with the v5 facets option. If you display one with resultBadgeKey, also add that attribute to attributesToRetrieve; see the resultBadgeKey reference.

V5 result breadcrumbs use the hierarchy.lvl0 through hierarchy.lvl6 values generated from your selectors. Keep the heading levels ordered and include the hierarchy attributes in attributesToRetrieve.

Boost search results with `pageRank` Copy Section

This parameter allows you to boost records using a custom ranking attribute built from the current pathsToMatch. Pages with highest pageRank will be returned before pages with a lower pageRank. The default value is 0 and you can pass any numeric value as a string, including negative values.

Search results are sorted by weight (desc), so you can have both boosted and non boosted results. The weight of each result will be computed for a given query based on multiple factors: match level, position, etc. and the pageRank value will be added to this final weight. The pageRank on its own may not be enough to influence the results of your query depending on how your overall ranking is set up. If changing the pageRank value doesn't influence your search results enough, even with large values, move weight.pageRank higher in the Ranking and Sorting page for your index.

You can view the computed weight directly from the Algolia dashboard (dashboard.algolia.com->search->perform a search->mouse hover over the "ranking criteria" icon bottom right of each record). That will give you an idea of what pageRank value is acceptable for your case.

{
  indexName: "YOUR_INDEX_NAME",
  pathsToMatch: ["https://YOUR_WEBSITE_URL/api/**"],
  recordExtractor: ({ $, helpers, url }) => {
    const isDocPage = /\/[\w-]+\/docs\//.test(url.pathname);
    const isBlogPage = /\/[\w-]+\/blog\//.test(url.pathname);
    return helpers.docsearch({
      recordProps: {
        lvl0: {
          selectors: "header h1",
        },
        lvl1: "article h2",
        lvl2: "article h3",
        lvl3: "article h4",
        lvl4: "article h5",
        lvl5: "article h6",
        content: "article p, article li",
        pageRank: isDocPage ? "-2000" : isBlogPage ? "-1000" : "0",
      },
    });
  },
},

Reduce the number of records Copy Section

If you encounter the Extractors returned too many records error when your page outputs more than 750 records, the aggregateContent option helps you reduce the number of records at the content level of the extractor.

{
  indexName: "YOUR_INDEX_NAME",
  pathsToMatch: ["https://YOUR_WEBSITE_URL/api/**"],
  recordExtractor: ({ $, helpers }) => {
    return helpers.docsearch({
      recordProps: {
        lvl0: {
          selectors: "header h1",
        },
        lvl1: "article h2",
        lvl2: "article h3",
        lvl3: "article h4",
        lvl4: "article h5",
        lvl5: "article h6",
        content: "article p, article li",
      },
      aggregateContent: true,
    });
  },
},

Reduce the record size Copy Section

If you encounter the Records extracted are too big error, your records or source page might contain too much information. The recordVersion option reduces record size by removing fields used only by the DocSearch v2 UI.

{
  indexName: "YOUR_INDEX_NAME",
  pathsToMatch: ["https://YOUR_WEBSITE_URL/api/**"],
  recordExtractor: ({ $, helpers }) => {
    return helpers.docsearch({
      recordProps: {
        lvl0: {
          selectors: "header h1",
        },
        lvl1: "article h2",
        lvl2: "article h3",
        lvl3: "article h4",
        lvl4: "article h5",
        lvl5: "article h6",
        content: "article p, article li",
      },
      recordVersion: "v3",
    });
  },
},

`recordProps` API Reference Copy Chapter

`lvl0` Copy Section

type: Lvl0 | required

type Lvl0 = {
  selectors: string | string[];
  defaultValue?: string;
};

`lvl1`, `content` Copy Section

type: string | string[] | required

`lvl2`, `lvl3`, `lvl4`, `lvl5`, `lvl6` Copy Section

type: string | string[] | optional

`pageRank` Copy Section

type: number | optional

See the live example

Custom variables Copy Section

type: string | string[] | CustomVariable | optional

type CustomVariable =
  | {
      defaultValue: string | string[];
    }
  | {
      selectors: string | string[];
      defaultValue?: string | string[];
    };

Define custom variables in recordProps. You can use them with v5 facets and per-index filters.

`helpers.docsearch` API Reference Copy Chapter

`aggregateContent` Copy Section

type: boolean | default: true | optional

This option groups the Algolia records created at the content level of the selector into a single record for its matching heading.

`recordVersion` Copy Section

type: 'v3' | 'v2' | default: v2 | optional

This option selects the crawler record schema. It doesn't select the DocSearch UI package version. Set it to v3 to remove fields used only by the DocSearch v2 UI. The v3 value is also the current record schema for DocSearch v5 frontends.

`indexHeadings` Copy Section

type: boolean | { from: number, to: number } | default: true | optional

This option tells the crawler if the headings (lvlX) should be indexed.

• When false, only records for the content level will be created.
• When from, to is provided, only records for the lvlX to lvlY will be created.

Packages Website Docs Required Configuration (`packages/website/docs/required-configuration.mdx`) Copy Section

title: Required configuration Copy Chapter

Follow these requirements so the crawler can extract structured records from your website. Update your markup and crawler configuration where needed.

:::info

If your website uses one of the supported framework integrations, its generated markup might already meet these requirements. Confirm that the crawler selectors match your framework and version.

:::

Generic configuration example Copy Chapter

Start with the default DocSearch configuration template. For more customization options, see complex record extractors.

If you use a framework integration, see the configuration templates.

docsearch-default.js

/* Detailed source-code truncated for AI context efficiency. */

recordVersion: 'v3' selects the crawler record schema. It isn't the DocSearch UI version and works with the v5 frontend packages. If you expose lang, language, or version as v5 facets, add those attributes to attributesForFaceting. Keep a badge attribute in attributesToRetrieve when you pass it to resultBadgeKey.

Overview of a clear layout Copy Section

Use a page layout that separates documentation content from navigation and other page elements:

Use the main blue element as your .DocSearch-content container. Follow the next guidelines to structure its contents.

Use the right classes as [`recordProps`][2] Copy Section

Add static classes to identify each content role. These classes don't need to change the page's appearance. The crawler uses them to extract structured records.

• Add a static DocSearch-content class to the main container for your text. This container is usually a <main> or <article> element.

• Configure every searchable lvl element outside the main documentation container, such as a sidebar item, as a global selector. The crawler adds these elements to every record from the page. Keep levels in increasing order in the document flow: lvlX should follow lvlY when X > Y.

• Use standard heading elements, such as h1, h2, and h3, for lvlX selectors. You can also use static classes. Add a unique id or name attribute to each matching element.

• Give every element that matches an lvlX selector a unique id or name attribute. DocSearch uses this anchor to open the page at the matching element.

• V5 builds result breadcrumbs from the populated hierarchy.lvl0 through hierarchy.lvl6 attributes. Keep heading levels ordered, avoid gaps where possible, and retrieve the full hierarchy object.

• Wrap every element that matches the recordProps.content selector in a `` or <li> element. Split text into focused blocks, and don't nest matching elements because this creates duplicate records.

• Keep the content structure consistent throughout the document.

Introduce global information as meta tags Copy Chapter

The crawler automatically extracts information from DocSearch-specific meta tags:

<meta name="docsearch:language" content="en" />
<meta name="docsearch:version" content="1.0.0" />

The crawler adds the content value of these meta tags to every record extracted from the page. Each tag's name attribute must follow the docsearch:$NAME pattern, where $NAME is the record attribute to set.

The docsearch:version meta tag can be a set of comma-separated tokens, each of which is a version relevant to the page. These tokens must be compliant with the SemVer specification or only contain alphanumeric characters (e.g. latest, next, etc.). As facet filters, these version tokens are case-insensitive.

For example, add the following meta tag to assign two versions to every record on a page:

<meta name="docsearch:version" content="2.0.0-alpha.62,latest" />

The crawler adds the following version attribute to each record:

{
  "version": ["2.0.0-alpha.62", "latest"]
}

Add these attributes to attributesForFaceting. You can then use them in per-index facetFilters or expose up to five controls with the v5 facets option. To show version in each result, retrieve it and set resultBadgeKey to version.

Nice to have Copy Chapter

• Keep your sitemap up to date so the crawler can identify changed pages. The crawler also discovers eligible links from crawled pages.

• Ensure that every page provides its full context. Use global elements where appropriate.

• Make your documentation content available without client-side JavaScript rendering. If your website requires JavaScript rendering, set renderJavaScript: true in your configuration.

Any questions? Connect with us on Discord or support.

Packages Website Docs Styling (`packages/website/docs/styling.md`) Copy Section

title: Styling DocSearch Copy Chapter

Use @docsearch/css to style DocSearch v5.

The package provides a complete stylesheet and separate bundles for the button, keyword modal, Ask AI interface, and sidepanel. See CSS bundles and exports to choose the files for your integration.

Packages Website Docs Templates (`packages/website/docs/templates.mdx`) Copy Section

title: Config Templates Copy Chapter

import useBaseUrl from '@docusaurus/useBaseUrl';

Use these crawler configuration templates as a starting point for supported website generators. To add or update a template, contact us on Discord or open a pull request.

If you want to better understand the default parameters of the configs below, take a look at the Crawler documentation.

Getting started Copy Chapter

After approval, the onboarding flow creates a crawler with your URL and Algolia credentials. If it detects one of the listed generators, it can assign the matching template. Otherwise, it applies the default template.

These templates configure indexing, not the installed DocSearch frontend package. In a template, recordVersion: 'v3' means the crawler's v3 record schema; it doesn't mean DocSearch UI v3.

For v5 facets, add each custom filter attribute to attributesForFaceting and expose no more than five keys in the frontend. For resultBadgeKey, add the selected property to attributesToRetrieve. Keep hierarchy.lvl0 through hierarchy.lvl6 populated and retrievable so v5 can render result breadcrumbs. See the v5 JavaScript API reference.

Update a template Copy Chapter

You can manually update the crawler template by going to dashboard.algolia.com, click "Data sources", select your crawler, and go to the editor page. From there you can edit the JavaScript directly. Note that you can make draft changes without saving, test the changes using the "URL Tester", and then "Save" once you're happy with your changes.

Default template Copy Chapter

default.js

/* Detailed source-code truncated for AI context efficiency. */

Docusaurus v1 template Copy Chapter

docusaurus-v1.js

/* Detailed source-code truncated for AI context efficiency. */

Docusaurus v2 and later template Copy Chapter

docusaurus-v2.js

/* Detailed source-code truncated for AI context efficiency. */

Astro Starlight Template Copy Chapter

starlight.js

/* Detailed source-code truncated for AI context efficiency. */

Vuepress v1 Template Copy Chapter

vuepress-v1.js

/* Detailed source-code truncated for AI context efficiency. */

Vuepress v2 Template Copy Chapter

vuepress-v2.js

/* Detailed source-code truncated for AI context efficiency. */

Vitepress Template Copy Chapter

vitepress.js

/* Detailed source-code truncated for AI context efficiency. */

Rspress Template Copy Chapter

rspress.js

/* Detailed source-code truncated for AI context efficiency. */

pkgdown Template Copy Chapter

pkgdown.js

/* Detailed source-code truncated for AI context efficiency. */

Packages Website Docs Tips (`packages/website/docs/tips.md`) Copy Section

title: Tips for a good search Copy Chapter

DocSearch works with many website structures, but consistent structure can improve relevance and indexing time. Follow these recommendations to improve your DocSearch results.

Use a `sitemap.xml` Copy Chapter

If you provide a sitemap in your crawler configuration, DocSearch uses it to find pages to index. The crawler also follows eligible links on those pages.

Add a sitemap.xml to your website if you don't have one. A sitemap can reduce indexing time and gives you more control over which pages are indexed.

Sitemaps can also improve search engine optimization. For more information, see the sitemaps specification.

Structure the hierarchy of information Copy Chapter

DocSearch works better on structured documentation. Result relevance uses the structural hierarchy of your content. The crawler reads the <h1> through <h6> headings or equivalent selectors to build hierarchy.lvl0 through hierarchy.lvl6.

Documentation usually introduces general concepts before covering details. Represent this structure with an ordered heading hierarchy. For example, content under an <h4> is more specific than content under an <h2> on the same page. Content that appears earlier on the page ranks higher.

DocSearch uses this structure to improve relevance. V5 also uses the populated hierarchy levels to render result breadcrumbs. Keep headings in order and avoid skipping levels where possible so each result retains its page context.

Choose a documentation depth that gives each result enough context. For large pages, use four levels, from lvl0 to lvl3. Use at least three levels.

You can use classes, such as ``, instead of <hX> elements.

Set a unique class to the element holding the content Copy Chapter

DocSearch extracts content based on the HTML structure. We recommend that you add a custom class to the HTML element wrapping all your textual content. This will help narrow selectors to the relevant content.

A unique identifier makes your configuration more robust and limits indexing to relevant content. Use it to exclude unrelated headers, sidebars, and footers.

Add anchors to headings Copy Chapter

Add a custom anchor to each heading. Define anchors with an id or name HTML attribute so browsers can scroll directly to the corresponding position. Links can target an anchor with # followed by its value.

DocSearch uses these anchors to send users to the location of the selected result.

Mark active pages in the navigation Copy Chapter

If you use multi-level navigation, mark each active level with a custom CSS class. The crawler can use this class to determine where the current page fits in the website hierarchy.

For example, if your troubleshooting.html page is located under the "Installation" menu in your sidebar, we recommend that you add a custom CSS class to the "Installation" and "Troubleshooting" links in your sidebar.

Use any valid CSS class name that can be part of a CSS selector.

Consistency of your content Copy Chapter

Use the same heading structure across documentation pages. Make each page topic and outline clear, and avoid selectors that create records without enough context, such as standalone introductions or asides.

Write selectors that match documentation pages but exclude landing pages, tables of contents, and other unrelated content. Add a dedicated class, such as .DocSearch-content, to the main documentation container.

Use consistent terms for the same concepts. You can also configure synonyms for terms your users search interchangeably.

Avoid duplicate content Copy Chapter

Split broad topics into focused pages. Avoid catch-all pages that make it difficult to identify the relevant result.

Duplicate content adds noise and can mislead users. Don't repeat all documentation content on a landing or summary page. If you need duplicate records for separate datasets, such as different versions, use facets to distinguish them.

Index metadata for v5 Copy Chapter

Add each attribute used by the v5 facets option to attributesForFaceting. DocSearch supports up to five facet controls. For a result badge, index a short value such as version, include it in attributesToRetrieve, and pass its property path to resultBadgeKey. See the v5 JavaScript API reference.

Conciseness Copy Chapter

Keep content focused on one task or concept, and use short headings and paragraphs.

For more guidance, read How to build a helpful search for technical documentation.

Packages Website Docs V5 Breaking Changes (`packages/website/docs/v5-breaking-changes.mdx`) Copy Section

title: v5 breaking changes Copy Chapter

This page lists the user-facing changes between the v4.6.0 package source and 5. Use it with the v4 migration guide.

JavaScript entry points Copy Chapter

The root export is AI-capable Copy Section

In v4, the root @docsearch/js export rendered the combined component and allowed Ask AI to be omitted. In v5, it renders DocSearchAI, and its DocSearchProps type requires askAi.

Use the root entry when you configure Agent Studio:

import docsearch from '@docsearch/js';

Keyword-only search moved to `/docsearch` Copy Section

Use the new subpath when you don't need Ask AI:

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

This entry excludes Ask AI code.

The UMD bundle is split Copy Section

• dist/umd/index.js includes keyword search and Ask AI.
• dist/umd/docsearch.js includes keyword search only.
• Both bundles expose window.docsearch.
• Loading both bundles causes the later script to replace the same global.

An exports map restricts JavaScript imports Copy Section

@docsearch/js now exports only . and ./docsearch. Replace imports of internal distribution files with one of these public entry points. Direct CDN URLs to the two documented UMD files remain supported by the package layout.

React components Copy Chapter

`DocSearch` is keyword-only Copy Section

V4's DocSearch accepted askAi and interceptAskAiEvent. V5's DocSearch contains keyword search only and no longer declares those props.

`DocSearchAI` owns the AI experience Copy Section

Use DocSearchAI for keyword search and Ask AI:

import { DocSearchAI } from '@docsearch/react';

DocSearchAIProps extends DocSearchProps, requires askAi, and adds interceptAskAiEvent.

The package also adds @docsearch/react/docsearchAi and @docsearch/react/askaiModal subpaths.

The Ask AI modal is separate Copy Section

DocSearchModal is keyword-only. DocSearchAskAiModal contains the combined keyword and AI modal. Composable integrations that rendered DocSearchModal with askAi must switch to DocSearchAskAiModal and its required provider callbacks. Review the Composable API instead of constructing these props without the provider.

@docsearch/modal exports the AI modal from its root and from @docsearch/modal/askai.

Ask AI and Agent Studio Copy Chapter

The legacy transport is removed Copy Section

V5 no longer requests a legacy Ask AI token or sends chat requests to the v4 Ask AI endpoint. All Ask AI conversations use the Agent Studio completions endpoint.

Create and configure an assistant in Agent Studio before upgrading.

`askAi.agentStudio` is removed Copy Section

The backend switch is no longer needed because Agent Studio is the only backend. Remove both agentStudio: true and agentStudio: false.

Flat Ask AI search parameters are removed Copy Section

DocSearchAskAi.searchParameters now always uses AgentStudioSearchParameters: an object keyed by index name.

searchParameters: {
  docs: {
    filters: 'language:en',
    attributesToRetrieve: ['title', 'content', 'url'],
    distinct: true,
  },
}

Each value supports filters, attributesToRetrieve, restrictSearchableAttributes, and distinct. The Agent Studio type omits facetFilters.

Agent Studio credentials are sent directly Copy Section

Ask AI requests use the configured application ID and API key in x-algolia-application-id and x-algolia-api-key headers. Memory authentication adds x-algolia-secure-user-token. Check the permissions and domain restrictions of keys that were issued for the legacy transport.

Feedback uses Agent Studio Copy Section

Feedback now posts to Agent Studio and supports negative-feedback reason tags and notes. Stored conversation messages can contain feedbackTags and feedbackNotes in addition to the like or dislike value.

Agent Studio configuration is nested under `askAi` Copy Section

Dynamic indices, custom tools, memory, and keyword promptSuggestions belong inside the askAi object. interceptAskAiEvent remains a top-level integration callback.

Suggested questions have two sources Copy Section

• askAi.suggestedQuestions determines whether DocSearch loads published questions for the assistant from algolia_ask_ai_suggested_questions on the new-conversation screen.
• askAi.promptSuggestions searches a configured index containing a prompt attribute and displays those prompts with keyword results.

These options aren't interchangeable.

Search configuration Copy Chapter

The Docusaurus adapter configuration changed Copy Section

The v5 adapter reads themeConfig.docsearch and rejects the former themeConfig.algolia key. It also requires indices and rejects indexName and root searchParameters.

Replace searchPagePath with searchPage. Move askAi.sidePanel to the root sidePanel option. Remove legacy Ask AI credentials and the askAi.agentStudio switch. Follow Migrate the Docusaurus adapter from v4 for before-and-after configurations.

Multiple indices share one result flow Copy Section

V5 creates one source for each index response and combines hit totals across responses. Result order follows the normalized index order. Review code that assumes one index or source identifier.

New keyword search behavior Copy Chapter

Facets add requests and filters Copy Section

The new facets option fetches facet values with a zero-hit query for every configured index. DocSearch merges and sorts values, supports at most five keys after trimmed, lowercase duplicate checks, and displays only facets with values.

A selected value is appended to that index's existing facetFilters. Account for the additional facet-value request in analytics, rate estimates, and search-client mocks.

Result badges require retrieved attributes Copy Section

The new resultBadgeKey reads a property path from each hit. The default attributesToRetrieve list doesn't include custom badge properties. Add them to each relevant index's searchParameters.attributesToRetrieve.

Result markup and grouping changed Copy Section

V5 refreshes the modal and result markup, renders breadcrumbs, introduces source panels, and adds facet and badge elements. CSS selectors, DOM tests, snapshots, and custom overrides that target v4 internals can break.

Use public component props for behavior and review Styling for visual changes.

Styles and builds Copy Chapter

Ask AI styles have a separate source bundle Copy Section

The complete @docsearch/css stylesheet still imports button, modal, and Ask AI rules. React also exposes split style entries:

• @docsearch/react/style/variables
• @docsearch/react/style/button
• @docsearch/react/style/modal
• @docsearch/react/style/askai
• @docsearch/react/style/sidepanel

If you assemble styles by component, add style/askai for DocSearchAI or DocSearchAskAiModal.

Generated React file names changed Copy Section

The documented package subpaths remain stable, but their targets changed from names such as dist/esm/DocSearchModal.js to generated entry files such as dist/esm/modal.js. Imports that bypassed the package exports can break.

The React `main` field now points to ESM Copy Section

@docsearch/react changes main from dist/umd/index.js to dist/esm/index.js. Consumers that resolve main instead of the package exports need an ESM-compatible build pipeline. The explicit unpkg and jsdelivr fields continue to point to dist/umd/index.js.

The browser target is ES2017 Copy Section

V5's tsdown builds target ES2017. Provide transpilation or polyfills if your browser support policy extends below that target.

Public controls Copy Chapter

JavaScript instances don't expose Sidepanel state Copy Section

DocSearchInstance exposes open, close, openAskAi, destroy, isReady, and isOpen. It doesn't expose openSidepanel, isSidepanelOpen, or isSidepanelSupported.

React refs include Sidepanel controls Copy Section

DocSearchRef exposes the JavaScript-style modal controls plus openSidepanel, isSidepanelOpen, and isSidepanelSupported. openSidepanel does nothing until a Sidepanel view registers. On mobile, openAskAi and standard Ask AI actions fall back to the modal.

See hybrid mode for the supported integration.

Deprecated keyboard hook fields remain Copy Section

UseDocSearchKeyboardEventsProps.onInput and searchButtonRef are accepted for compatibility but are deprecated and aren't used by the v5 React hook implementation.

Compatibility Copy Chapter

React peer range Copy Section

@docsearch/react, @docsearch/core, @docsearch/modal, and @docsearch/sidepanel declare these optional peers:

• react: >=16.8.0 <20.0.0
• react-dom: >=16.8.0 <20.0.0
• @types/react: >=16.8.0 <20.0.0

@docsearch/react also accepts optional search-insights versions >=1 <3.

Package versions must match Copy Section

The v5 packages depend on matching versions of the other DocSearch packages. Don't mix v4 and v5 packages in a Composable API or Sidepanel tree.

CSS remains a separate install for top-level integrations Copy Section

Install @docsearch/css@^5, then import @docsearch/css. For a CDN integration, load @docsearch/css/dist/style.css.

Additive v5 APIs Copy Chapter

These additions aren't breaking by themselves, but they replace common v4 custom implementations:

• facets and DocSearchFacet for keyword filters.
• resultBadgeKey for hit metadata.
• DocSearchAI and DocSearchAskAiModal for AI-capable React views.
• askAi.indices (string[]) for dynamic Agent Studio search indices.
• askAi.searchParameters for per-index runtime search overrides.
• ToolCalls and ToolDefinition for custom Agent Studio tools.
• Memory for user-scoped Agent Studio memory.
• PromptSuggestions for keyword-query prompt suggestions.
• Ask AI feedback tags and notes.
• Split JavaScript, React, and style entries for smaller keyword-only builds.

Packages Website Docs What Is Docsearch (`packages/website/docs/what-is-docsearch.md`) Copy Section

title: What is DocSearch? sidebar_label: What is DocSearch? Copy Chapter

Why? Copy Chapter

We created DocSearch because developers spend a lot of time reading documentation, and finding relevant information in large documentation sites can be difficult. Building good search is a challenge.

Algolia has extensive experience building search interfaces. We use that experience to extract content from technical documentation and make it searchable from the first keystroke.

Overview Copy Chapter

DocSearch has two independent parts: indexing and the frontend search experience.

• The Algolia Crawler extracts your documentation into an Algolia index. Use the Crawler interface to edit the crawler configuration, monitor crawls, and trigger new crawls.
• The DocSearch v5 packages query that index and render keyword search or Ask AI in your frontend. They are built on Algolia Autocomplete.

Crawler configuration and record schema versions don't select the installed DocSearch frontend package version. You can update the frontend package without changing how the crawler is scheduled.

How to feature DocSearch? Copy Chapter

DocSearch is free for eligible documentation sites. Read the eligibility requirements and apply. After approval and indexing, add a DocSearch v5 package or a supported framework integration to your website. Keep the "Search by Algolia" link displayed.

DocSearch is one of our ways to give back to the open source community for everything it did for us already.

You can now apply to the program

Packages Website Docs Who Can Apply (`packages/website/docs/who-can-apply.md`) Copy Section

title: Who can apply? Copy Chapter

Open to developer documentation and technical blogs.

We built DocSearch to improve search on large technical documentation sites. We offer the free DocSearch program to public technical documentation and technical blogs.

We usually turn down applications when they are not production ready or have non-technical content on the website.

Application process Copy Chapter

To apply to the DocSearch program, follow the onboarding process in the Algolia dashboard. Submit your domain for validation against the program requirements. If your domain meets the criteria, you can create your DocSearch crawler.

• Use one of our supported integrations or a DocSearch v5 package after your content is indexed.

• Verify your domain ownership within 7 days of approval to continue using the crawler.

• Review the DocSearch Plan Terms and Conditions.

Process duration Copy Chapter

The application process includes automated validation. If we can't determine your eligibility automatically, we'll conduct a manual review that may take one to two business days.

Once approved, continue the onboarding process to create your DocSearch crawler. After the crawler indexes your data, choose the frontend package or framework integration separately. Updating the frontend doesn't change your crawler or index format.

Packages Website Docs Agent Studio Dynamic Indices (`packages/website/docs/agent-studio/dynamic-indices.mdx`) Copy Section

title: Configure dynamic indices Copy Chapter

Pass askAi.indices when Agent Studio should search a specific set of indices for this request. This lets each DocSearch instance choose which indices the agent can use.

This property isn't the same as the top-level indices property:

• Top-level indices configures DocSearch keyword search. Entries are index names or objects with a name property.
• askAi.indices configures Agent Studio search. Entries are index name strings.

Agent Studio completions accept index names only. Put index descriptions and tool defaults on the agent configuration in Agent Studio. Put per-index runtime overrides in askAi.searchParameters.

The agent's Algolia Search tool must use mode: "dynamic". If the tool's static index list is empty, also enable allowUnlistedIndices.

Select indices Copy Chapter

<DocSearchAI
  appId="YOUR_APPLICATION_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['docs']}
  askAi={{
    agentId: 'YOUR_AGENT_ID',
    indices: ['docs_markdown', 'api_reference'],
    searchParameters: {
      docs_markdown: {
        filters: 'visibility:public',
        attributesToRetrieve: ['title', 'content', 'url'],
      },
      api_reference: {
        distinct: false,
      },
    },
  }}
/>

`indices` Copy Section

type: string[] | optional

Index names available to the Agent Studio search tool for this request. When omitted, Agent Studio uses the indices configured on the agent tool.

Set request-wide search parameters Copy Chapter

askAi.searchParameters is keyed by index name:

askAi: {
  agentId: 'YOUR_AGENT_ID',
  indices: ['docs_markdown'],
  searchParameters: {
    docs_markdown: {
      filters: 'visibility:public',
      attributesToRetrieve: ['title', 'content', 'url'],
      distinct: false,
    },
  },
}

Supported override fields are filters, attributesToRetrieve, restrictSearchableAttributes, distinct, userToken, enablePersonalization, personalizationImpact, and optionalFilters.

Don't use the flat search-parameter shape from earlier DocSearch AI integrations.

Docusaurus validation Copy Chapter

The v5 Docusaurus adapter requires at least one string when you set askAi.indices. Contextual search merges version/language filters into askAi.searchParameters[index].filters for each dynamic index name.

See the React package reference and Docusaurus adapter guide for the complete types.

Packages Website Docs Agent Studio Feedback (`packages/website/docs/agent-studio/feedback.mdx`) Copy Section

title: Collect response feedback Copy Chapter

DocSearch v5 includes feedback controls for completed Agent Studio answers. You don't need to add an askAi option to enable them.

Use an API key with the search ACL. Agent Studio accepts one vote per message. See Agent Studio feedback for service requirements and reporting details.

Understand the ratings Copy Chapter

Thumbs up submits positive feedback immediately:

{
  thumbs: 1;
}

Thumbs down opens a form before submission. A user can select zero or more reason tags and add an optional note:

{
  thumbs: 0;
  tags?: AskAiFeedbackReason[];
  notes?: string;
}

Closing or canceling the form doesn't submit feedback. Submitting without a reason or note is valid. DocSearch trims notes, omits an empty note, and limits notes to 1,000 characters.

DocSearch supports these reason values:

Reason tags and notes are collected only for negative feedback.

Understand submission behavior Copy Chapter

DocSearch sends the Agent Studio agent ID, message ID, vote, and optional negative-feedback details to Agent Studio. After a successful request, it shows a thank-you state and records the rating with the locally stored conversation.

If submission fails, DocSearch keeps the negative-feedback form open and displays the error so the user can retry.

Change feedback labels Copy Chapter

Override feedback text through translations.modal.askAiScreen:

<DocSearchAI
  appId="YOUR_APPLICATION_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['docs']}
  askAi={{ agentId: 'YOUR_AGENT_ID' }}
  translations={{
    modal: {
      askAiScreen: {
        likeButtonTitle: 'Helpful',
        dislikeButtonTitle: 'Not helpful',
        thanksForFeedbackText: 'Feedback received',
        feedbackPanelTitle: 'Tell us what went wrong',
        feedbackDetailsPlaceholder: 'Add details',
        feedbackSubmitButtonText: 'Send feedback',
        feedbackTagIncorrect: 'Incorrect or incomplete',
        feedbackTagNotWhatIAsked: 'Not what I asked for',
        feedbackTagSlowOrBuggy: 'Slow or buggy',
        feedbackTagStyleOrTone: 'Style or tone',
        feedbackTagSafetyOrLegal: 'Safety or legal concern',
        feedbackTagOther: 'Other',
      },
    },
  }}
/>

See the React package reference for all feedback translation keys and the exported feedback types.

Packages Website Docs Agent Studio Memory (`packages/website/docs/agent-studio/memory.mdx`) Copy Section

title: Add user-scoped memory Copy Chapter

Agent Studio memory lets an agent retain useful context for a user across conversations. Configure memory in Agent Studio first, then give DocSearch a secure user token so Agent Studio can isolate each user's data.

Read the Agent Studio memory overview before enabling memory in production.

Generate a secure user token Copy Chapter

Generate the JWT on your backend after authenticating the user. Follow the Agent Studio user authentication guide for the required claims, signing algorithm, and key ID.

Protect the token flow:

• Never generate the token in browser code.
• Never expose the Algolia secret key used to sign it.
• Use a stable, non-sensitive user identifier in the JWT sub claim.
• Set an expiration and refresh expired tokens.
• Serve the token only over HTTPS.
• Don't put sensitive user data in JWT claims. JWT payloads aren't encrypted.

Pass the token to DocSearch Copy Chapter

Fetch a token from your backend and pass it as memory.userToken:

const response = await fetch('/api/agent-studio-token', {
  credentials: 'include',
});
const { userToken } = await response.json();

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: ['docs'],
  askAi: {
    agentId: 'YOUR_AGENT_ID',
    memory: {
      enabled: true,
      userToken,
    },
  },
});

Use the same askAi.memory object with React's DocSearchAI.

When userToken is present, DocSearch sends it in the X-Algolia-Secure-User-Token request header. When it's absent, DocSearch omits the header. Don't use unscoped memory for a multi-user application.

`memory.enabled` Copy Chapter

type: boolean | optional

Controls whether DocSearch displays Agent Studio's built-in memory tool activity:

• algolia_memorize displays that information was saved.
• algolia_ponder and algolia_memory_search display that memory was used.
• Memory tool errors aren't displayed.

The default is false.

This option doesn't enable memory in Agent Studio and doesn't create a user identity. Configure the feature on the agent and pass userToken for user isolation. DocSearch sends userToken when provided even if enabled is false.

A custom entry in askAi.tools with the same memory tool name replaces the built-in memory rendering.

See the JavaScript package reference or React package reference for the Memory configuration type.

Packages Website Docs Agent Studio Migrate To Agent Studio (`packages/website/docs/agent-studio/migrate-to-agent-studio.mdx`) Copy Section

title: Migrate Ask AI to Agent Studio Copy Chapter

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

Ask AI is now part of Agent Studio. Migrate your existing Ask AI assistant, publish the new agent, then point DocSearch at the agent ID.

DocSearch v5 uses Agent Studio as its only AI backend. There's no agentStudio flag.

If you're still on DocSearch v4, follow the v4 migration guide. To upgrade packages at the same time, see Migrate from DocSearch v4.

Migrate your assistant Copy Chapter

1. Start the migration in the dashboard Copy Section

1. Sign in to the Algolia dashboard.
2. Open Ask AI.
3. Select your assistant and click Migrate to Agent Studio.

The wizard creates a draft Agent Studio agent from your assistant configuration, including the prompt, model, indices, and related settings. After migration, the assistant and agent are independent and don't stay in sync.

2. Review and publish the agent Copy Section

1. Open Agents in Agent Studio.
2. Review the migrated agent.
3. Publish the agent when you're ready to go live.

Copy the agent ID. DocSearch calls this value agentId in its public API.

3. Update your integration Copy Section

Choose the path that matches how you embed Ask AI today:

• DocSearch v5
• Custom Ask AI API

Your existing Ask AI assistant keeps serving traffic until Ask AI is fully retired. Switch your client to the Agent Studio agent when you're ready.

Update DocSearch v5 Copy Chapter

Pass the Agent Studio agent ID as askAi.agentId, or as the askAi string shorthand. Rename any assistantId field to agentId.

import { DocSearchAI } from '@docsearch/react';
import '@docsearch/css';

export function Search() {
  return (
    <DocSearchAI
      appId="YOUR_APPLICATION_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['YOUR_DOCSEARCH_INDEX']}
      askAi={{
        agentId: 'YOUR_AGENT_ID',
      }}
    />
  );
}

<DocSearchAI
  appId="YOUR_APPLICATION_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['YOUR_DOCSEARCH_INDEX']}
  askAi="YOUR_AGENT_ID"
/>

import docsearch from '@docsearch/js';
import '@docsearch/css';

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

Update `searchParameters` Copy Section

Agent Studio search parameters are keyed by index name. Move any flat Ask AI searchParameters under the index:

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'],
+    },
   },
 }

Supported keys are filters, attributesToRetrieve, restrictSearchableAttributes, and distinct. Don't put facetFilters in this object. Put fixed facet conditions in filters. For per-request index selection, see dynamic indices.

Docusaurus adapter Copy Section

The adapter requires themeConfig.docsearch.askAi as an object with agentId. It rejects the string shorthand and the removed agentStudio property. See the Docusaurus adapter guide.

Custom Ask AI API integrations Copy Chapter

If you call the Ask AI HTTP API yourself instead of using DocSearch, configure your client for Agent Studio instead of https://askai.algolia.com.

Don't build new integrations against the Ask AI chat API. Use the Agent Studio APIs:

• Integrate Agent Studio
• Agent Studio API
• Completions endpoint example:
  https://{APPLICATION_ID}.algolia.net/agent-studio/1/agents/{AGENT_ID}/completions

Authenticate with your application ID and a search-only API key. Prefer the DocSearch configuration above when you embed DocSearch—the SDK wires the Agent Studio transport for you.

Next steps Copy Chapter

After the agent ID is live in DocSearch:

• Get started with Agent Studio
• Dynamic indices
• Tools
• Memory
• Prompt suggestions
• Feedback

Packages Website Docs Agent Studio Prompt Suggestions (`packages/website/docs/agent-studio/prompt-suggestions.mdx`) Copy Section

title: Configure prompt suggestions Copy Chapter

DocSearch v5 can show questions in three places. Each source has a different purpose and configuration.

• Suggested questions appear on the new-conversation screen. They come from published records for the agent in the fixed suggested-questions index. Configure them with suggestedQuestions: true.
• Keyword prompt suggestions appear while the user types in keyword search. They come from your Algolia prompt-suggestions index. Configure them with promptSuggestions.
• Streamed follow-ups appear below the latest completed answer. They come from data-suggestions streamed by Agent Studio. Configure suggestions on the agent.

Show suggested questions Copy Chapter

Enable curated starting questions with suggestedQuestions:

askAi: {
  agentId: 'YOUR_AGENT_ID',
  suggestedQuestions: true,
}

DocSearch queries the algolia_ask_ai_suggested_questions index for records where state is published and assistantId matches the configured agent. It requests up to three records.

A suggested-question record has this shape, plus its Algolia objectID:

{
  appId: string;
  assistantId: string;
  question: string;
  locale?: string;
  state: 'published';
  source: string;
  order: number;
}

When a user selects one, DocSearch sends its objectID as suggestedQuestionId with the question.

Show prompt suggestions during keyword search Copy Chapter

Create an Algolia index whose records contain a prompt string, then configure its name:

askAi: {
  agentId: 'YOUR_AGENT_ID',
  promptSuggestions: {
    indexName: 'docs_prompt_suggestions',
    hitsPerPage: 3,
  },
}

As the user types, DocSearch searches this index with the entered query and retrieves only the prompt attribute. It places matching prompts after the action that asks the entered text directly.

hitsPerPage defaults to 3. The Docusaurus adapter requires a positive value. If this search fails, DocSearch keeps the direct Ask AI action and omits the suggestions.

Selecting a prompt starts Agent Studio with that prompt. It doesn't send a suggestedQuestionId.

Show streamed follow-ups Copy Chapter

Configure contextual suggestions in the Agent Studio agent editor. See write and configure agent prompts.

Agent Studio streams these follow-ups in a data-suggestions part. DocSearch renders its suggestions array below the latest answer only. Selecting one sends it as the next user message in the same conversation.

There's no DocSearch askAi option for streamed follow-ups. If Agent Studio doesn't stream data-suggestions, DocSearch doesn't show them.

See the JavaScript package reference and React package reference for the suggestion options and translation keys.

Packages Website Docs Agent Studio Tools (`packages/website/docs/agent-studio/tools.mdx`) Copy Section

title: Add tools Copy Chapter

Use tools to let your agent read live data or perform actions. Configure the tool and its input schema in Agent Studio, then add a matching entry to askAi.tools when DocSearch needs to run or render it.

See Agent Studio tools before exposing a tool to users.

Add a client-side tool Copy Chapter

The key in tools must match the tool name configured in Agent Studio.

import { DocSearchAI, type ToolCalls } from '@docsearch/react';

const tools: ToolCalls = {
  getAccountPlan: {
    translations: {
      callingToolText: 'Checking your account',
    },
    render({ message: { input, output } }) {
      const result = output as { plan?: string } | undefined;
      return result?.plan ? `Account plan: ${result.plan}` : '';
    },
    async onToolCall({ input, addToolOutput }) {
      const response = await fetch('/api/account-plan', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify(input),
      });

      const output = await response.json();
      await addToolOutput({ output });
    },
  },
};

export function Search() {
  return (
    <DocSearchAI
      appId="YOUR_APPLICATION_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={['docs']}
      askAi={{
        agentId: 'YOUR_AGENT_ID',
        tools,
      }}
    />
  );
}

The JavaScript package accepts the same askAi.tools object.

Every tool definition requires render. DocSearch calls it after output is available and passes both input and output. Return a string to show a result, or an empty string to show nothing.

Add onToolCall for a tool that runs in the browser. It receives:

• input: the arguments selected by the agent. Treat this value as untrusted and validate it.
• toolCallId: the current call ID.
• toolName: the configured tool name.
• dynamic: whether the streamed call was marked as dynamic, when provided.
• addToolOutput: the function that returns the result to the conversation.

Call addToolOutput({ output }) after your work finishes. DocSearch invokes onToolCall without waiting for its returned promise, so handle failures inside the callback.

Keep browser tools within the signed-in user's permissions. Don't place service credentials in the tool definition. Call your backend for privileged work. See client-side tool security.

For React, define tools outside the component or memoize it. Recreating the object doesn't change behavior, but a stable object avoids rebuilding dependent configuration.

Render server-side or MCP tools Copy Chapter

If Agent Studio executes a tool, omit onToolCall and provide render under the streamed tool name. DocSearch uses the output returned by Agent Studio.

const tools = {
  get_release_status: {
    render({ message: { output } }) {
      const status = output?.status;
      return status ? `Release status: ${status}` : '';
    },
  },
};

Understand Algolia MCP search tools Copy Chapter

DocSearch recognizes these Agent Studio search tool names without a tools entry:

• algolia_search_index
• Any name beginning with algolia_search_index_

The recognized input includes query, index, optional number_of_results, and optional facet_filters. The output can include hits, nbHits, and queryId.

DocSearch shows search progress and the query used by the tool. It combines consecutive completed search calls into one search summary when more than one call has a nonempty query. A non-search message part ends the group.

You can add a matching tools entry to replace the built-in rendering for a search or memory tool. Your custom renderer takes precedence.

To connect other MCP servers to an agent, see MCP tools in Agent Studio. See the React package reference for ToolCalls and ToolDefinition.

Use tools with Docusaurus Copy Chapter

Docusaurus removes functions while serializing theme configuration. The v5 adapter rejects askAi.tools and sidePanel.tools in docusaurus.config. Swizzle @theme/SearchBar and pass tools to the modal or Sidepanel from React instead.

See the Docusaurus adapter guide for the supported configuration.

Packages Website Docs Mcp Installation (`packages/website/docs/mcp/installation.mdx`) Copy Section

title: Install DocSearch MCP sidebar_label: Installation Copy Chapter

import MCPInstall from '@site/src/components/mcp/MCPInstall';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs';

DocSearch MCP is a remote MCP server. Point any MCP-compatible client at this endpoint — no authentication required:

https://mcp.algolia.com/1/docsearch/mcp

The fastest path to getting started is the DocSearch CLI — one command that configures your client for you. Prefer to set things up yourself? Install it as a plugin (ships the MCP server plus client guidance like rules, skills, and commands) or manually (just the MCP server config). Pick your client below.

/plugin marketplace add algolia/docsearch
/plugin install algolia-docsearch@algolia-docsearch-marketplace

mcp/plugins/docsearch/cursor/algolia-docsearch

{
  "mcpServers": {
    "algolia-docsearch": {
      "url": "https://mcp.algolia.com/1/docsearch/mcp"
    }
  }
}

claude mcp add --scope user --transport http algolia-docsearch https://mcp.algolia.com/1/docsearch/mcp

codex mcp add algolia-docsearch --url https://mcp.algolia.com/1/docsearch/mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "algolia-docsearch": {
      "type": "remote",
      "url": "https://mcp.algolia.com/1/docsearch/mcp",
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "algolia-docsearch": {
      "httpUrl": "https://mcp.algolia.com/1/docsearch/mcp"
    }
  }
}

Use DocSearch MCP to find the Next.js middleware matcher documentation.

How do I configure middleware matchers in Next.js?

Show me the Stripe webhook signature verification documentation.

What is the setup for Algolia InstantSearch React?

Use DocSearch MCP to look up React Server Components data fetching.

/algolia-docsearch:docs <library-or-product> [topic]

/algolia-docsearch:docs Next.js middleware matcher
/algolia-docsearch:docs Stripe webhook signature verification
/algolia-docsearch:docs Algolia InstantSearch React configure search client

docsearch docs Next.js "how do middleware matchers work"

docsearch docs Next.js "cache revalidation" --max-results 3 --max-docsets 2

docsearch resolve "Algolia InstantSearch React"
docsearch query repo/algolia/instantsearch "configure the React search client"

docsearch resolve Next.js --top-n 3

docsearch docs Next.js "cache revalidation" --json

{
  "library": "Next.js",
  "query": "how do middleware matchers work"
}

https://mcp.algolia.com/1/docsearch/mcp

docsearch setup --project --cursor --yes
docsearch setup --global --all --yes

interface KeyboardShortcuts {
  'Ctrl/Cmd+K'?: boolean;
  '/'?: boolean;
  'Ctrl/Cmd+I'?: boolean;
}

type InitialAskAiMessage = {
  query: string;
  messageId?: string;
  suggestedQuestionId?: string;
};

function useDocSearch(): DocSearchContext;

function useKeyboardShortcuts(
  userShortcuts?: KeyboardShortcuts
): Required<KeyboardShortcuts>;

function useTheme(props: { theme?: 'dark' | 'light' }): void;

interface UseDocSearchKeyboardEventsProps {
  isOpen: boolean;
  onOpen: () => void;
  onClose: () => void;
  isAskAiActive: boolean;
  onAskAiToggle: (active: boolean) => void;
  keyboardShortcuts?: KeyboardShortcuts;
  onInput?: (event: KeyboardEvent) => void;
  searchButtonRef?: React.RefObject<HTMLButtonElement | null>;
}

import '@docsearch/css';
import '@docsearch/css/dist/style.css';

import '@docsearch/css/dist/button.css';

import '@docsearch/css/dist/button.css';
import '@docsearch/css/dist/modal.css';

import '@docsearch/css';

import '@docsearch/css';
import '@docsearch/css/dist/sidepanel.css';

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/style.css"
/>

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@docsearch/css@^5/dist/sidepanel.css"
/>

npm install @docsearch/css@^5

yarn add @docsearch/css@^5

pnpm add @docsearch/css@^5

bun add @docsearch/css@^5

import '@docsearch/css';

import '@docsearch/css';
import '@docsearch/css/dist/sidepanel.css';

:root {
  --docsearch-primary-color: #2457d6;
  --docsearch-primary-dark-color: #173b99;
  --docsearch-focus-color: #0b57d0;
  --docsearch-modal-width: 48rem;
  --docsearch-modal-radius: 0.75rem;
  --docsearch-hit-height: 3.75rem;
  --docsearch-border-radius: 0.375rem;
}

html[data-theme='dark'] {
  --docsearch-modal-background: #111827;
  --docsearch-background-color: #1f2937;
  --docsearch-text-color: #f3f4f6;
  --docsearch-secondary-text-color: #d1d5db;
  --docsearch-hit-background: #111827;
  --docsearch-hit-focus-background: #263244;
}

.DocSearch-Button {
  min-width: 15rem;
}

.DocSearch-Sidepanel-Container.floating {
  box-shadow: 0 1rem 3rem rgb(0 0 0 / 20%);
}

.DocSearch-Action:focus-visible,
.DocSearch-Button:focus-visible {
  outline: 2px solid var(--docsearch-focus-color);
  outline-offset: 2px;
}

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APPLICATION_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: ['YOUR_INDEX_NAME'],
    },
  },
};

indices: [
  'docs_en',
  {
    name: 'api_reference',
    searchParameters: {
      facetFilters: ['version:v5'],
      filters: 'visibility:public',
      attributesToRetrieve: [
        'content',
        'hierarchy',
        'type',
        'url',
        'version',
      ],
      restrictSearchableAttributes: ['hierarchy', 'content'],
      distinct: true,
    },
  },
],

docsearch: {
  // ...
  contextualSearch: false,
},

docsearch: {
  // ...
  facets: [
    { key: 'language', label: 'Language' },
    { key: 'version', label: 'Version' },
  ],
},

docsearch: {
  // ...
  indices: [
    {
      name: 'docs',
      searchParameters: {
        attributesToRetrieve: [
          'content',
          'hierarchy',
          'type',
          'url',
          'version',
        ],
      },
    },
  ],
  resultBadgeKey: 'version',
},

searchPage: {
  path: 'find',
  facets: [
    { attribute: 'hierarchy.lvl0', label: 'Section' },
    { attribute: 'version', label: 'Version' },
  ],
},

searchPage: false,

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  suggestedQuestions: true,
  searchParameters: {
    docs: {
      filters: 'visibility:public',
      attributesToRetrieve: ['title', 'content', 'url'],
      distinct: true,
    },
  },
  memory: {
    enabled: true,
    userToken: 'SERVER_GENERATED_JWT',
  },
  promptSuggestions: {
    indexName: 'docs_prompt_suggestions',
    hitsPerPage: 3,
  },
},

askAi: {
  agentId: 'YOUR_ASSISTANT_ID',
  indices: ['docs_markdown'],
  searchParameters: {
    docs_markdown: {
      filters: 'language:en',
    },
  },
},

sidePanel: {
  variant: 'inline',
  side: 'right',
  width: 420,
  expandedWidth: '60vw',
  pushSelector: '#__docusaurus',
  suggestedQuestions: true,
  hideButton: false,
  keyboardShortcuts: {
    'Ctrl/Cmd+I': true,
  },
},

npm run swizzle -- @docsearch/docusaurus-adapter SearchBar --eject

import type { DocusaurusSearchBarProps } from '@docsearch/docusaurus-adapter';
import type { ToolCalls } from '@docsearch/react';
import OriginalSearchBar from '@theme-original/SearchBar';

const tools: ToolCalls = {
  getReleaseStatus: {
    render: ({ message }) => JSON.stringify(message.output),
  },
};

export default function SearchBar(props: DocusaurusSearchBarProps) {
  return (
    <OriginalSearchBar
      {...props}
      askAi={{
        assistantId: 'YOUR_ASSISTANT_ID',
        tools,
      }}
      sidePanel={{ tools }}
    />
  );
}

import OriginalSearchBar from '@theme-original/SearchBar';

const tools = {
  getReleaseStatus: {
    render: ({ message }) => JSON.stringify(message.output),
  },
};

export default function SearchBar(props) {
  return (
    <OriginalSearchBar
      {...props}
      askAi={{
        assistantId: 'YOUR_ASSISTANT_ID',
        tools,
      }}
      sidePanel={{ tools }}
    />
  );
}

translations: {
  button: {
    buttonText: 'Search API docs',
    buttonAriaLabel: 'Search API docs',
  },
  modal: {
    searchBox: {
      placeholderText: 'Search API docs',
    },
    facets: {
      clearAllLabel: 'Reset filters',
    },
    resultsScreen: {
      resultBadgeLabelText: 'Version',
    },
  },
},

docsearch: {
  // ...
  externalUrlRegex: '^https://external\\.example\\.com/',
  replaceSearchResultPathname: {
    from: '/legacy-docs/',
    to: '/docs/',
  },
},

`themeConfig.algolia` is no longer supported by @docsearch/docusaurus-adapter v5. Move the configuration to `themeConfig.docsearch`.

`themeConfig.docsearch.indexName` was removed. Use `themeConfig.docsearch.indices` instead.

`themeConfig.docsearch.searchParameters` was removed. Configure `searchParameters` on each `themeConfig.docsearch.indices` entry instead.

`themeConfig.docsearch.searchPagePath` was removed. Use `themeConfig.docsearch.searchPage` instead.

`themeConfig.docsearch.askAi` must be an object with `assistantId`.

`themeConfig.docsearch.askAi.agentStudio` was removed. The adapter now only supports Agent Studio.

`themeConfig.docsearch.askAi.indexName`, `apiKey`, and `appId` were removed. Use the top-level DocSearch credentials instead.

`themeConfig.docsearch.askAi.sidePanel` was removed. Use `themeConfig.docsearch.sidePanel` instead.

`themeConfig.docsearch.sidePanel` requires `themeConfig.docsearch.askAi`.

`themeConfig.docsearch.askAi.tools` is not supported because Docusaurus removes function values when serializing theme config. Pass custom tools through a swizzled `@theme/SearchBar` component instead: use `askAi` for the modal and `sidePanel` for the side panel.

`themeConfig.docsearch.sidePanel.tools` is not supported because Docusaurus removes function values when serializing theme config. Pass custom tools through a swizzled `@theme/SearchBar` component instead: use `askAi` for the modal and `sidePanel` for the side panel.

"themeConfig.docsearch" is required
"docsearch.appId" is required. If you haven't migrated to the new DocSearch infra, please refer to the blog post for instructions: https://docusaurus.io/blog/2021/11/21/algolia-docsearch-migration
"docsearch.apiKey" is required
"docsearch.indices" is required
"docsearch.indices" must contain at least 1 items
"docsearch.unknownKey" is not allowed
"docsearch.askAi.indices" must contain at least 1 items
"docsearch.askAi.indices[0]" must be a string
"docsearch.sidePanel.indices" must contain at least 1 items
"docsearch.sidePanel.indices[0]" must be a string

npm install @docsearch/docusaurus-adapter@^5

yarn add @docsearch/docusaurus-adapter@^5

pnpm add @docsearch/docusaurus-adapter@^5

bun add @docsearch/docusaurus-adapter@^5

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    algolia: {
      appId: 'YOUR_APPLICATION_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'docs',
    },
  },
};

export default {
  plugins: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APPLICATION_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [{ name: 'docs' }],
    },
  },
};

docsearch: {
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'docs',
  searchParameters: {
    facetFilters: ['language:en'],
    attributesToRetrieve: ['content', 'hierarchy', 'type', 'url'],
  },
},

docsearch: {
  appId: 'YOUR_APPLICATION_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indices: [
    {
      name: 'docs',
      searchParameters: {
        facetFilters: ['language:en'],
        attributesToRetrieve: ['content', 'hierarchy', 'type', 'url'],
      },
    },
  ],
},

searchPagePath: 'find',

searchPage: {
  path: 'find',
  facets: [
    { attribute: 'hierarchy.lvl0', label: 'Section' },
    { attribute: 'version', label: 'Version' },
  ],
},

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  appId: 'ASK_AI_APPLICATION_ID',
  apiKey: 'ASK_AI_SEARCH_API_KEY',
  indexName: 'docs_markdown',
  agentStudio: true,
},

askAi: 'YOUR_ASSISTANT_ID',

askAi: {
  agentId: 'YOUR_ASSISTANT_ID',
  indices: ['docs_markdown'],
},

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  searchParameters: {
    filters: 'language:en',
    attributesToRetrieve: ['title', 'content', 'url'],
  },
},

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  searchParameters: {
    docs: {
      filters: 'language:en',
      attributesToRetrieve: ['title', 'content', 'url'],
    },
  },
},

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  sidePanel: {
    variant: 'inline',
    side: 'right',
  },
},

askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
},
sidePanel: {
  variant: 'inline',
  side: 'right',
},

npm run swizzle -- @docsearch/docusaurus-adapter SearchBar --eject

import type { DocusaurusSearchBarProps } from '@docsearch/docusaurus-adapter';
import type { ToolCalls } from '@docsearch/react';
import OriginalSearchBar from '@theme-original/SearchBar';

const tools: ToolCalls = {
  getReleaseStatus: {
    render: ({ message }) => JSON.stringify(message.output),
  },
};

export default function SearchBar(props: DocusaurusSearchBarProps) {
  return (
    <OriginalSearchBar
      {...props}
      askAi={{ assistantId: 'YOUR_ASSISTANT_ID', tools }}
      sidePanel={{ tools }}
    />
  );
}

import OriginalSearchBar from '@theme-original/SearchBar';

const tools = {
  getReleaseStatus: {
    render: ({ message }) => JSON.stringify(message.output),
  },
};

export default function SearchBar(props) {
  return (
    <OriginalSearchBar
      {...props}
      askAi={{ assistantId: 'YOUR_ASSISTANT_ID', tools }}
      sidePanel={{ tools }}
    />
  );
}

facets: [
  { key: 'language', label: 'Language' },
  { key: 'version', label: 'Version' },
],

indices: [
  {
    name: 'docs',
    searchParameters: {
      attributesToRetrieve: [
        'content',
        'hierarchy',
        'type',
        'url',
        'version',
      ],
    },
  },
],
resultBadgeKey: 'version',

import docsearch from '@docsearch/js';

const instance = docsearch(options);

interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}

indices: [
  {
    name: 'docs_en',
    searchParameters: {
      facetFilters: ['version:v5'],
      attributesToRetrieve: [
        'hierarchy.lvl0',
        'hierarchy.lvl1',
        'hierarchy.lvl2',
        'hierarchy.lvl3',
        'hierarchy.lvl4',
        'hierarchy.lvl5',
        'hierarchy.lvl6',
        'content',
        'type',
        'url',
        'version',
      ],
    },
  },
  'docs_fr',
];

interface DocSearchFacet {
  key: string;
  label?: string;
}

facets: [
  { key: 'language', label: 'Language' },
  { key: 'version', label: 'Version' },
];

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',

docsearch({
  hitComponent({ hit, children }, { html }) {
    return html`<a href=${hit.url} data-result-type=${hit.type}>${children}</a>`;
  },
  resultsFooterComponent({ state }, { html }) {
    return html`<p>No results found for query: ${state.query}</p>`;
  },
  footerAction(_, { html }) {
    return html`<a href="https://algolia.com">Our other project</a>`;
  },
});

askAi: 'YOUR_ASSISTANT_ID';