Search

DocSearch has two halves. A crawler, run by Algolia (or by you, for sites that are not eligible for the free program or sit behind a firewall), visits the deployed site and writes records into an Algolia index. The default preset generates a sitemap.xml that the crawler can use. The browser then queries the index through the Algolia API from a modal opened from the navbar.

The sequence diagram shows the two halves. The crawler runs on a schedule (weekly by default, adjustable in the Algolia interface), and you can trigger a crawl from the Algolia dashboard after a significant change. The browser step uses only the public, search-only API key. The last step is done by the theme: hits are absolute URLs of the deployed site, and the theme turns each one into a relative URL with the site baseUrl applied so the click is handled by the single-page application router instead of a full page load.

The following docusaurus.config.ts is a complete configuration for Pocket Units. The identifiers come from environment variables so the same file works in CI; the fallbacks are placeholders, not real values.

Source: Docusaurus docs: Search

A build of this configuration (with the default scaffold content) succeeds and produces the search page, the OpenSearch description and the search button in the navbar:

The generated build folder contains search/index.html (the results page), opensearch.xml, and every page has a head tag that points to the description:

Source: Docusaurus docs: Search

The navbar contains a button whose class is DocSearch-Button and whose label is "Search" with a keyboard shortcut hint. Clicking it loads the modal code on demand, so the DocSearch modal and its CSS are not part of the initial bundle.

The options of themeConfig.algolia are:

Any other DocSearch option put in the algolia object is passed to the DocSearch component, because the validation accepts unknown keys in that object.

The product name and the npm versions are easy to confuse, so it is worth being exact. Algolia publishes the DocSearch front end as @docsearch/react (and @docsearch/js), and the current major is 5: both packages had 5.1.2 as their latest tag on 2026-10-26, with 4.7.1 under the latest-v4 tag. Docusaurus 3.10.2 does not use v5. The @docusaurus/theme-search-algolia 3.10.2 package declares the dependency range ^3.9.0 || ^4.3.2 for @docsearch/react, and the scratch site resolved it to 4.7.1. So:

Do not install @docsearch/react 5 next to this theme: it is outside the range the theme declares. The version in use selects the Ask AI behaviour described next. The theme decides at build time with version.startsWith('3.').

Contextual search is on by default. At runtime the theme builds Algolia facet filters from the page the reader is on: one filter language:<locale> and a group of docusaurus_tag:<tag> filters. The tags come from <meta> tags written into the HTML, which the crawler also records. In the scratch build, a docs page contains:

The tag docs-default-current identifies the docs plugin instance (default) and the version (current); for a versioned site the tag changes with the version, so a reader on version 1.0 sees hits for 1.0 and for unversioned pages (tag default) only. The home page carries the tag default. This is why the index must have facets on the attributes the Docusaurus documentation lists (docusaurus_tag, language, lang, version and type): if search finds nothing, but works with contextualSearch: false, the usual cause is an index created without those facets. The official fix is to use Algolia’s recommended Docusaurus crawler configuration, delete the index, and crawl again; the crawler’s initialIndexSettings apply only when the index is first created.

To control the filtering yourself set contextualSearch: false and write searchParameters.facetFilters, for example one filter per product line. Setting both merges them. See Versioning and Internationalization for how versions and locales appear in the index.

Ask AI lets a reader ask a question in natural language from the same modal and get an answer based on the indexed documentation. It arrived with DocSearch v4 support in Docusaurus 3.9 and is off unless you configure it: the library being v4 does not enable it. You create an assistant in the Algolia dashboard, then reference it from themeConfig.algolia.askAi, either as the assistant identifier alone:

Source: Docusaurus 3.9 release notes

or as an object when the assistant uses a different index or key:

Source: Docusaurus docs: Search

The object accepts assistantId (required), indexName, apiKey, appId, searchParameters (with facetFilters) and suggestedQuestions. What you leave out is filled from the top-level algolia values when the configuration is validated, and the top-level facetFilters are copied when the object has none; the contextual filters are merged in at runtime, so an assistant sees the same language and version scoping as the search. The documentation describes recent questions, conversation history and a bring-your-own-LLM option, with the LLM provider’s usage billed to you, and requires an Algolia index with the Ask AI assistant enabled. The object form was built successfully (the build does not contact Algolia) and the string form follows the same validation path; the answers themselves were not tested because they need an Algolia account.

The theme refuses to build when Ask AI is configured but the installed @docsearch/react is a 3.x version. In that case the build stops with this message:

The message suggests ^4.0.0; on Docusaurus 3.10.2 the range the theme declares is ^3.9.0 || ^4.3.2, so prefer ^4.3.2 when you pin it.

A missing required key is reported at the start of the build. With apiKey removed, the scratch build fails with:

A missing appId gives the same kind of error with an extra hint to read the DocSearch infrastructure migration post. The usual reason for either is an environment variable that is not set in CI and no fallback in the config.

The modal has its own accessible styling. It is customised with DocSearch CSS variables in src/css/custom.css, set separately for the light theme and for [data-theme='dark']. The Docusaurus documentation lists --docsearch-primary-color, --docsearch-text-color, --docsearch-muted-color, --docsearch-container-background, --docsearch-modal-background, --docsearch-searchbox-background, --docsearch-searchbox-focus-background, --docsearch-hit-color, --docsearch-hit-active-color, --docsearch-hit-background, --docsearch-footer-background and --docsearch-key-gradient. A typical use is to point the primary colour at the Infima variable so the modal follows the site theme:

Source: Docusaurus docs: Search

See Styling, Theming and Swizzling for Infima variables and dark mode.

DocSearch is free for developer documentation and technical blogs that meet Algolia’s eligibility checklist; you apply to the program and Algolia sends the set-up details by email. A site that is not eligible can run its own crawler against its own Algolia account. Ask AI is a separate feature with its own requirements, described above.

A wrapper renders the original component and adds to it. The following command creates the wrapper file:

The generated wrapper imports the original through the @theme-original alias. Adding a link to the results page next to the button gives:

Source: Docusaurus docs: Swizzling

The build succeeded and the navbar HTML ends with <a class="navbar__item navbar__link" href=/search>All results</a> right after the DocSearch button. Prefer wrapping to ejecting: it keeps your code small and keeps the behaviour that the theme may improve later.

To provide a completely different search, make a component named src/theme/SearchBar/index.tsx that does not import the original. The Docusaurus documentation suggests either swizzling the empty SearchBar of the classic theme or starting from the Algolia one. This minimal replacement has no JavaScript search at all: a form that sends the query to an external engine restricted to the site host. It is a stand-in to show the mechanism, not a recommendation.

Source: Docusaurus docs: Search

In a site with no search theme this builds and the navbar contains the form, with the input named q and the hidden sites input set to the host of url. A real replacement would query your own API. The useSearchLinkCreator hook of @docusaurus/theme-common builds links to the results page, which the Algolia modal uses for its "see all results" link.