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

Getting Started with v4

warning

DocSearch v4 is currently in beta. While it's suitable for production scenarios, expect potential improvements and minor issues. Use at your discretion.

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@beta
# or with npm
npm install @docsearch/js@beta

Without package manager​

Include CSS in your website's <head>

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

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

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@beta"></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 AskAI​

DocSearch v4 introduces support for AskAI, Algolia’s advanced, AI-powered search capability. AskAI enhances the user experience by providing contextually relevant and intelligent responses directly from your documentation

To enable AskAI, add your Algolia Assistant ID to your DocSearch configuration:

docsearch({
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
});

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'],
  },
});

Sending events​

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

docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
  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.