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​

DocSearch packages are available on the npm registry.

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.

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, or search parameters):

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.

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.