DocSearch v3

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.

JavaScript

yarn add @docsearch/js@alpha# ornpm install @docsearch/js@alpha

If you don’t want to use a package manager, you can use a standalone endpoint:

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

React

yarn add @docsearch/react@alpha# ornpm install @docsearch/react@alpha

If you don’t want to use a package manager, you can use a standalone endpoint:

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

Get started

JavaScript

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

React

DocSearch generates a fully accessible search box for you.

import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
function App() {  return (    <DocSearch      appId="YOUR_APP_ID"      indexName="YOUR_INDEX_NAME"      apiKey="YOUR_SEARCH_API_KEY"    />  );}
export default App;

Testing

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

JavaScript

docsearch({  appId: 'BH4D9OD16A',  apiKey: '25626fae796133dc1e734c6bcaaeac3c',  indexName: 'docsearch',});

React

<DocSearch  appId="BH4D9OD16A"  apiKey="25626fae796133dc1e734c6bcaaeac3c"  indexName="docsearch"/>

Filtering your search

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.

JavaScript

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

React

<DocSearch  // ...  searchParameters={{    facetFilters: ['language:en', 'version:1.0.0'],  }}/>

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 />