How to Configure Search Functionality with Algolia in Docusaurus

Configure Algolia search in Docusaurus by adding an algolia object to themeConfig in your docusaurus.config.js file with your Application ID, search-only API key, and index name.

Docusaurus ships with the @docusaurus/theme-search-algolia theme, which provides a fast, client-side Algolia DocSearch experience. According to the facebook/docusaurus source code, the entire integration is controlled through the themeConfig.algolia field, validated at build time by a Joi schema, and consumed at runtime by React hooks and UI components.

Configuration Basics

All Algolia settings live inside the themeConfig object of your site configuration. When using the classic preset, Docusaurus automatically injects the Algolia theme into the build pipeline, as seen in packages/docusaurus/src/server/plugins/__tests__/__fixtures__/presets/preset-themes.js where ['@docusaurus/theme-algolia', opts.algolia] is registered.

Required Credentials

The algolia object requires three mandatory fields validated by packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts:

• appId – Your Algolia Application ID (e.g., 'X1Z85QJPUV').
• apiKey – A search-only API key. Never use a write key here.
• indexName – The name of the Algolia index containing your crawled documentation (e.g., 'docusaurus-2').

Optional Configuration Flags

Beyond the required credentials, Docusaurus supports several optional fields to customize search behavior:

• contextualSearch – Boolean (default: true). When enabled, Docusaurus automatically adds facet filters for the current version, language, and site path, limiting results to the user's current context.
• searchParameters – Object passed directly to Algolia's search method. Use this to set custom facetFilters, hitsPerPage, or other Algolia parameters.
• searchPagePath – String (default: 'search'). Defines the path for the dedicated search results page (e.g., /search).
• askAi – Object or String (DocSearch v4 only). Configures the "Ask AI" assistant feature. A string value represents the assistant ID, while an object allows overriding assistantId, indexName, apiKey, and appId.

Build-Time Validation

Docusaurus validates your Algolia configuration during site generation to prevent runtime errors. The validation logic resides in packages/docusaurus-theme-search-algolia/src/validateThemeConfig.ts, which uses Joi to enforce the schema.

This validator ensures required fields are present, applies defaults (such as contextualSearch: true), and provides helpful error messages if mandatory values are missing. For example, if you provide an askAi configuration while using DocSearch v3, the build will throw an error referencing the version mismatch check at lines 63-66 of the validation file.

Runtime Architecture

Once validated, the configuration flows through Docusaurus's context system to the UI layer:

1. useAlgoliaThemeConfig – Implemented in packages/docusaurus-theme-search-algolia/src/client/useAlgoliaThemeConfig.ts, this React hook reads the validated Algolia config from the global Docusaurus context.
2. SearchBar – Located at packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx, this component imports the hook, retrieves the credentials, and instantiates the Algolia DocSearch client (@docsearch/react) to perform browser-side searches.
3. Contextual Filtering – When contextualSearch is enabled, the client automatically appends facet filters for the active version and language, ensuring results remain scoped to the current documentation context.

Implementation Examples

Minimal Algolia Configuration

Add the following to your docusaurus.config.js (referenced in examples/classic/docusaurus.config.js):

/** @type {import('@docusaurus/types').Config} */
const config = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true, // default, can be omitted
      searchParameters: {
        facetFilters: ['lang:en'],
      },
    },
  },
};

export default config;

Enabling the "Ask AI" Feature (DocSearch v4)

Configure the AI assistant using either a simple string or full object notation:

themeConfig: {
  algolia: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    // Simple string form
    askAi: 'my-assistant-id',
    // Full object form for advanced control:
    // askAi: {
    //   assistantId: 'my-assistant-id',
    //   suggestedQuestions: true,
    //   // Optional overrides:
    //   // indexName: 'override-index',
    //   // apiKey: 'override-key',
    // }
  },
},

Accessing Config in Custom Components

Import the useAlgoliaThemeConfig hook to read Algolia settings inside your own React components:

import React from 'react';
import {useAlgoliaThemeConfig} from '@docusaurus/theme-search-algolia/client';

export default function CustomSearchInfo() {
  const {algolia} = useAlgoliaThemeConfig();
  return (
    <div>
      <p>Search Index: {algolia.indexName}</p>
      <pre>{JSON.stringify(algolia, null, 2)}</pre>
    </div>
  );
}

Summary

• Configuration Location: Define Algolia credentials inside themeConfig.algolia in docusaurus.config.js.
• Validation: The schema in validateThemeConfig.ts enforces required fields (appId, apiKey, indexName) at build time.
• Runtime Flow: The useAlgoliaThemeConfig hook exposes settings to the SearchBar component, which initializes the DocSearch client.
• Contextual Search: Enabled by default via contextualSearch: true, automatically filtering results by version and language.
• Modern Features: DocSearch v4 supports the askAi parameter for AI-assisted search, validated separately from legacy options.

Frequently Asked Questions

What Algolia credentials do I need for Docusaurus?

You need three values: your Application ID (appId), a search-only API key (apiKey), and your index name (indexName). These are configured in docusaurus.config.js under themeConfig.algolia. The search-only key is essential for security, as it prevents client-side write operations to your index.

How does Docusaurus handle search context filtering?

Docusaurus automatically manages contextual filtering through the contextualSearch option, which defaults to true. As implemented in the SearchBar component, this feature injects facet filters for the current documentation version and language into every query, ensuring users only see results relevant to the page they are currently viewing.

Can I use the Algolia configuration in my custom theme components?

Yes. Import the useAlgoliaThemeConfig hook from @docusaurus/theme-search-algolia/client to access the validated Algolia configuration object within any React component. This hook reads from Docusaurus's global context, providing access to appId, apiKey, indexName, and other settings defined in your config file.

What is the "Ask AI" feature in Docusaurus search?

The askAi configuration option enables DocSearch v4's AI assistant capabilities. You can configure it as a simple string (the assistant ID) or as an object with additional overrides. This feature is strictly validated in validateThemeConfig.ts and requires DocSearch v4; attempting to use it with v3 will trigger a build-time error.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}