Skip to main content
Version: Stable (v4.x)

Getting Started with v4

Introductionโ€‹

DocSearch v4 provides a significant upgrade over previous versions, offering enhanced accessibility, responsiveness, and an improved search experience for your documentation. Built on Algolia Autocomplete, DocSearch v4 ensures a seamless integration trusted by leading documentation sites worldwide.

Installationโ€‹

Looking for the Composable API documentation? You can find it here.

DocSearch packages are available on the npm registry.

Docusaurus usersโ€‹

If your docs site is powered by Docusaurus, use @docsearch/docusaurus-adapter for the latest DocSearch features (including new Ask AI capabilities such as sidepanel support), while keeping @docusaurus/preset-classic.

yarn add @docsearch/js@4
# or with npm
npm install @docsearch/js@4

Without package managerโ€‹

Include CSS in your website's <head>

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />

And the JavaScript at the end of your <body>:

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

Optimize first query performanceโ€‹

Enhance your users' first search experience by using preconnect, see Performance optimization below

Implementationโ€‹

DocSearch requires a dedicated container in your HTML

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

Initialize DocSearch by passing your container:

import docsearch from '@docsearch/js';

import '@docsearch/css';

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

DocSearch generates an accessible, fully-functional search input for you automatically.

Quick Testing (without credentials)โ€‹

If you'd like to test DocSearch immediately without your own credentials, use our demo configuration:

docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
  askAi: 'askAIDemo',
});

Or use our new dedicated DocSearch Playground

Using DocSearch with Ask AIโ€‹

DocSearch v4 introduces support for Ask AI, Algolia's advanced, AI-powered search capability. Ask AI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation. You can also use the same askAi configuration object to route chat through Agent Studio.

To enable Ask AI, you can add your Algolia Assistant ID as a string, or use an object for more advanced configuration (such as specifying a different index, credentials, search parameters, or enabling Agent Studio):

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});
  • Use the string form for a simple setup.
  • Use the object form to customize which index, credentials, or filters Ask AI uses.
  • The suggested questions feature is controlled on the Dashboard in the Ask AI section.

Using Agent Studio with DocSearchโ€‹

To use Algolia Agent Studio as the chat backend, set agentStudio: true inside the askAi object.

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    agentStudio: true,
    searchParameters: {
      YOUR_INDEX_NAME: {
        filters: 'type:content AND language:en',
        attributesToRetrieve: ['title', 'content', 'url'],
        restrictSearchableAttributes: ['title', 'content'],
        distinct: 'url',
      },
    },
  },
});
  • agentStudio is configured inside askAi, not as a top-level DocSearch prop.
  • When agentStudio: true, searchParameters must be keyed by index name.
  • Agent Studio search parameters support filters, attributesToRetrieve, restrictSearchableAttributes, and distinct.

Filtering search resultsโ€‹

If your website uses DocSearch meta tags or if you've added custom variables to your config, you'll be able to use the facetFilters option to scope your search results to a facet

This is useful to limit the scope of the search to one language or one version.

docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});

Ask AIโ€‹

Filtering also applies when using Ask AI. This is useful to limit the scope of the LLM's search to only relevant results.

info

We recommend using the facetFilters option when using Ask AI with multiple languages or any multi-faceted index.

docsearch({
  askAi: {
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      facetFilters: ['language:en', 'version:1.0.0'],
    },
  },
});
tip

You can use facetFilters: ['type:content'] to ensure Ask AI only uses records where the type attribute is content (i.e., only records that actually have content). This is useful if your index contains records for navigation, metadata, or other non-content types.

Sending eventsโ€‹

You can send search events to your DocSearch index by passing in the insights parameter when creating your DocSearch instance.

docsearch({
   // other options
+  insights: true,
});

Performance optimizationโ€‹

Preconnectโ€‹

Improve the loading speed of your initial search request by adding this snippet into your website's <head> section:

<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />

This helps the browser establish a quick connection with Algolia, enhancing user experience, especially on mobile devices.