Skip to main content
DocSearch provides a native Docusaurus theme that replaces the default search functionality with Algolia-powered search. The adapter is specifically designed for Docusaurus v3 and integrates seamlessly with the Docusaurus ecosystem.

​
Prerequisites

  • Docusaurus v3.9.2 or higher
  • Node.js 20.0 or higher
  • React 18.0+ or React 19.0+

​
Installation

Install the @docsearch/docusaurus-adapter package: 
npm install @docsearch/docusaurus-adapter
Don’t have your Algolia credentials yet? Apply to DocSearch to get started for free.

​
Configuration

1

Add to Docusaurus config

Configure DocSearch in your docusaurus.config.js file using the themeConfig.docsearch option:
docusaurus.config.js
export default {
  // ... other config
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};
The themeConfig.algolia configuration is still supported as a backward-compatible alias, but themeConfig.docsearch is the recommended approach.
2

Configure the theme (optional)

If you want to customize the search experience, add the theme to your docusaurus.config.js:
docusaurus.config.js
export default {
  // ... other config
  themes: ['@docsearch/docusaurus-adapter'],
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};

​
Complete Configuration Example

Here’s a comprehensive example with common options:
docusaurus.config.js
export default {
  title: 'My Documentation',
  url: 'https://docs.example.com',
  baseUrl: '/',
  
  themes: ['@docsearch/docusaurus-adapter'],
  
  themeConfig: {
    navbar: {
      title: 'My Docs',
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
    
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      
      // Optional: Contextual search filters
      contextualSearch: true,
      
      // Optional: Path for the search page
      searchPagePath: 'search',
      
      // Optional: External URL regex
      externalUrlRegex: 'external\\.com|another-domain\\.com',
      
      // Optional: Replace search results URLs
      replaceSearchResultPathname: {
        from: '/docs/',
        to: '/',
      },
      
      // Optional: Algolia search parameters
      searchParameters: {
        facetFilters: ['language:en', ['version:1.0', 'version:2.0']],
      },
      
      // Optional: Ask AI configuration
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: true,
      },
    },
  },
};

​
Configuration Options

​
Required Options

​
appId
string
required
Your Algolia application ID.
​
apiKey
string
required
Your Algolia Search API key (public, search-only key).
​
indexName
string
required
The name of your Algolia index to search.

​
Search Behavior Options

​
contextualSearch
boolean
Enables contextual search, which filters results based on the current documentation version and language. Defaults to false.When enabled, DocSearch automatically adds facet filters based on:
  • Current documentation version
  • Current language
  • Current documentation plugin ID
​
searchParameters
object
Additional Algolia search parameters to apply to all queries.
searchParameters: {
  facetFilters: ['language:en', 'version:2.0'],
  hitsPerPage: 10,
}
​
searchPagePath
boolean | string
Path to the search page. Set to false to disable the search page. Defaults to 'search'.When enabled, adds a “See all results” link at the bottom of the search modal.
​
externalUrlRegex
string
Regular expression to identify external URLs. Results matching this pattern will open in a new window instead of using client-side routing.
externalUrlRegex: 'external\\.com|another-domain\\.com'
​
replaceSearchResultPathname
object
Replace parts of the search result URLs before navigation.
replaceSearchResultPathname: {
  from: '/docs/',
  to: '/'
}

​
UI Customization Options

​
placeholder
string
Placeholder text for the search input. Defaults to 'Search docs'.
​
translations
object
Localized strings for the search interface. Docusaurus automatically provides translations for supported locales.
translations: {
  button: {
    buttonText: 'Buscar',
    buttonAriaLabel: 'Buscar documentación'
  },
  modal: {
    searchBox: {
      resetButtonTitle: 'Borrar búsqueda',
      cancelButtonText: 'Cancelar'
    }
  }
}

​
Ask AI Options

​
askAi
object
Configuration for the Ask AI feature.
askAi: {
  assistantId: 'YOUR_ASSISTANT_ID',
  sidePanel: true,
  apiKey: 'YOUR_AI_API_KEY',  // Optional, uses search apiKey by default
  appId: 'YOUR_AI_APP_ID',    // Optional, uses search appId by default
  indexName: 'YOUR_AI_INDEX', // Optional, uses search indexName by default
  suggestedQuestions: true,   // Show suggested questions
}
​
askAi.assistantId
string
required
The Algolia Assistant ID for Ask AI functionality.
​
askAi.sidePanel
boolean
Enable the side panel UI for Ask AI. When true, Ask AI opens in a side panel instead of replacing the search modal. Defaults to false.
​
askAi.suggestedQuestions
boolean
Show suggested questions in the Ask AI interface. Defaults to false.
​
askAi.apiKey
string
API key for Ask AI. If not provided, uses the main apiKey.
​
askAi.appId
string
App ID for Ask AI. If not provided, uses the main appId.
​
askAi.indexName
string
Index name for Ask AI. If not provided, uses the main indexName.
Contextual search automatically filters results based on the current page context. This is especially useful for versioned or multi-language documentation.
docusaurus.config.js
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
    },
  },
};
With contextual search enabled, DocSearch automatically adds facet filters:
  • Version: version:2.0 (based on the current doc version)
  • Language: language:en (based on the current locale)
  • DocPlugin: docusaurus_tag:docs-default-current (based on the plugin ID)
You can search across multiple Algolia indices:
docusaurus.config.js
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indices: [
        {
          name: 'docs_v1',
          searchParameters: {
            facetFilters: ['version:1.0']
          }
        },
        {
          name: 'docs_v2',
          searchParameters: {
            facetFilters: ['version:2.0']
          }
        },
        'blog', // Simple string for index without custom parameters
      ],
    },
  },
};

​
Ask AI Side Panel

The side panel provides a persistent AI assistant alongside your documentation:
docusaurus.config.js
export default {
  themeConfig: {
    docsearch: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      askAi: {
        assistantId: 'YOUR_ASSISTANT_ID',
        sidePanel: true,
        suggestedQuestions: true,
      },
    },
  },
};
When sidePanel: true, users can:
  • Open the side panel with a dedicated button in the navbar
  • Keep the panel open while browsing documentation
  • Switch between search and Ask AI seamlessly

​
Custom Styling

DocSearch inherits Docusaurus theme colors automatically. You can further customize with CSS:
src/css/custom.css
:root {
  --docsearch-primary-color: var(--ifm-color-primary);
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(94, 100, 112, 0.8);
  --docsearch-modal-background: var(--ifm-background-color);
  --docsearch-searchbox-background: var(--ifm-background-surface-color);
  --docsearch-footer-background: var(--ifm-background-surface-color);
}

[data-theme='dark'] {
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-container-background: rgba(47, 55, 69, 0.7);
  --docsearch-modal-background: var(--ifm-background-color);
  --docsearch-searchbox-background: var(--ifm-background-surface-color);
  --docsearch-footer-background: var(--ifm-background-surface-color);
  --docsearch-hit-background: var(--ifm-background-surface-color);
  --docsearch-hit-shadow: none;
}

​
Programmatic Access

You can access DocSearch programmatically in Docusaurus using client modules:
src/clientModules/searchControl.js
import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';

if (ExecutionEnvironment.canUseDOM) {
  // Wait for DocSearch to initialize
  window.addEventListener('load', () => {
    const searchButton = document.querySelector('.DocSearch-Button');
    
    // Custom button to trigger search
    const customButton = document.getElementById('my-search-button');
    if (customButton && searchButton) {
      customButton.addEventListener('click', () => {
        searchButton.click();
      });
    }
  });
}
Register the client module in docusaurus.config.js:
docusaurus.config.js
export default {
  clientModules: [
    require.resolve('./src/clientModules/searchControl.js'),
  ],
};

​
Migration from Algolia Plugin

If you’re migrating from @docusaurus/theme-search-algolia:
1

Install the new package

npm install @docsearch/docusaurus-adapter
2

Update configuration

Change themeConfig.algolia to themeConfig.docsearch:
docusaurus.config.js
  export default {
    themeConfig: {
-     algolia: {
+     docsearch: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
      },
    },
  };
3

Update deprecated options

Replace searchPagePath boolean with string or false:
  docsearch: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
-   searchPagePath: true,
+   searchPagePath: 'search',
  }
The themeConfig.algolia configuration continues to work as a backward-compatible alias, so you can migrate at your own pace.

​
Troubleshooting

​
Search not appearing

Ensure you have added the search component to your navbar:
docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

​
No results found

Verify your index exists and contains data:
  1. Check your Algolia dashboard
  2. Ensure your indexName matches exactly
  3. Verify apiKey has search permissions
  4. Check that contextual filters aren’t too restrictive

​
Styling conflicts

If DocSearch styles conflict with your theme:
src/css/custom.css
/* Reset conflicting styles */
.DocSearch-Button {
  /* Your custom styles */
}

​
Next Steps

Configuration

Learn about all available configuration options

Styling

Customize the appearance of your search

Ask AI

Enable AI-powered search assistance

Crawler Configuration

Configure the DocSearch crawler for your site

Build docs developers (and LLMs) love

Get started for freeTalk to us