# How to Configure Search Functionality with Algolia in Docusaurus

> Easily configure Algolia search in Docusaurus. Add the algolia object to themeConfig in docusaurus.config.js with your App ID, API key, and index name for powerful search.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Configure Algolia search in Docusaurus by adding an `algolia` object to `themeConfig` in your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) (referenced in [`examples/classic/docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/examples/classic/docusaurus.config.js)):

```javascript
/** @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:

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

```tsx
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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js).
- **Validation**: The schema in [`validateThemeConfig.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/validateThemeConfig.ts) and requires DocSearch v4; attempting to use it with v3 will trigger a build-time error.