Skip to main content
Version: current

Getting Started

info

The following content is for DocSearch v3. If you are using DocSearch v2, see the legacy documentation.

Introduction​

DocSearch v3 is built on top of the latest version of Algolia Autocomplete, which provides better accessibility, increased responsiveness, themability, a better built-in design, and customizability under low-network conditions.

This version has been rewritten in React, and now exposes React components. The vanilla JavaScript version is based on the React version with an alias to Preact.

Stable version​

With the recent release of the stable version of Algolia Autocomplete, and the huge adoption of DocSearch v3, we will start working on a stable release!

Thanks to all the Alpha testers, and to all the integrations who already support it!

Installation​

DocSearch packages are available on the npm registry.

yarn add @docsearch/js@3
# or
npm install @docsearch/js@3

Without package manager​

If you don't want to use a package manager, you can add the CSS to the <head> of your website:

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

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

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

Improve first query speed​

You can hint the browser to improve the speed of the first query by adding a preconnect, see #preconnect

Implementation​

To get started, you need a container for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:

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

Then, insert DocSearch into it by calling the docsearch function and providing the container. It can be a CSS selector or an Element.

Make sure to provide a container (for example, a div), not an input. DocSearch generates a fully accessible search box for you.

import docsearch from '@docsearch/js';

import '@docsearch/css';

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

Testing​

If you're eager to test DocSearch v3 and can't wait to receive your credentials, you can use ours!

docsearch({
  appId: 'R2IYF7ETH7',
  apiKey: '599cec31baffa4868cae4e79f180729b',
  indexName: 'docsearch',
});

If your website supports 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​

By adding this snippet to the head of your website, you can hint the browser that the website will load data from Algolia, and allows it to preconnect to the DocSearch cluster. It makes the first query faster, especially on mobile.

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