JavaScript Installation

DocSearch provides a standalone JavaScript package that works in any web application without requiring a framework. The package internally uses Preact for rendering while exposing a simple vanilla JS API.

Installation

Install the @docsearch/js package using your preferred package manager:

npm install @docsearch/js

yarn add @docsearch/js

pnpm add @docsearch/js

CDN Installation

If you prefer not to use a package manager, you can load DocSearch directly from a CDN:

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

Basic Setup

Import DocSearch and styles

Import the docsearch function and CSS styles in your application:

import docsearch from '@docsearch/js';
import '@docsearch/css';

Add a container element

Add a container element to your HTML where DocSearch will be rendered. DocSearch generates a fully accessible search box for you, so use a container element (like a div), not an input:

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

Initialize DocSearch

Call the docsearch() function with your configuration. You can pass either a CSS selector string or an HTML element:

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

Don’t have your Algolia credentials yet? Apply to DocSearch to get started for free.

Complete Example

Here’s a complete working example:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>DocSearch Example</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
</head>
<body>
  <div id="docsearch"></div>
  
  <script type="module">
    import docsearch from 'https://cdn.jsdelivr.net/npm/@docsearch/js@4/+esm';
    
    docsearch({
      container: '#docsearch',
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    });
  </script>
</body>
</html>

API Reference

docsearch(props)

The main function that initializes DocSearch and returns a control instance.

Parameters

string | HTMLElement

required

The container for your DocSearch component. Can be a CSS selector string or an HTMLElement.

string

required

Your Algolia application ID.

string

required

Your Algolia Search API key (public, search-only key).

string

required

The name of your Algolia index to search.

string

Placeholder text for the search input. Defaults to “Search docs”.

object

Additional Algolia search parameters to apply to all queries.

searchParameters: {
  hitsPerPage: 10,
  facetFilters: ['version:1.0']
}

function

Hook to transform search results before rendering.

transformItems: (items) => {
  return items.map(item => ({
    ...item,
    url: item.url.replace('https://example.com', '')
  }));
}

function

Custom component to render individual search results. Supports JSX, HTML strings with the html helper, or function-based templates.

hitComponent: ({ hit, children }, { html }) => {
  return html`<a href="${hit.url}" class="custom-hit">${children}</a>`;
}

function

Custom component rendered at the bottom of the results panel.

resultsFooterComponent: ({ state }, { html }) => {
  return html`<div class="footer">Showing ${state.collections.length} results</div>`;
}

function

Hook to wrap or modify the Algolia search client.

transformSearchClient: (searchClient) => {
  searchClient.addAlgoliaAgent('my-app', '1.0.0');
  return searchClient;
}

number

Maximum number of results to show per category. Defaults to 5.

boolean

Disable storage and display of recent and favorite searches. Defaults to false.

string

Query string to prefill when opening the search modal.

Return Value

The docsearch() function returns a DocSearchInstance object with the following methods:

boolean

Returns true once the component is mounted and ready.

boolean

Returns true if the modal is currently open.

function

Opens the search modal programmatically.

function

Closes the search modal programmatically.

function

Opens Ask AI mode in the modal.

search.openAskAi({ query: 'How do I get started?' });

function

Unmounts the DocSearch component and cleans up resources.

Programmatic Control

You can control DocSearch programmatically using the returned instance:

const search = docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'YOUR_INDEX_NAME',
  onReady: () => {
    console.log('DocSearch is ready!');
  },
  onOpen: () => {
    console.log('Search modal opened');
  },
  onClose: () => {
    console.log('Search modal closed');
  },
});

// Open the search modal programmatically
document.getElementById('custom-search-button').addEventListener('click', () => {
  search.open();
});

// Check if modal is open
console.log(search.isOpen); // true or false

// Open Ask AI with a pre-filled message
search.openAskAi({ query: 'How do I configure search?' });

// Clean up when done
search.destroy();

Lifecycle Callbacks

DocSearch supports lifecycle callbacks to hook into important events:

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'YOUR_INDEX_NAME',
  
  // Called when DocSearch is mounted and ready
  onReady: () => {
    console.log('DocSearch mounted');
  },
  
  // Called when the modal opens
  onOpen: () => {
    console.log('Modal opened');
  },
  
  // Called when the modal closes
  onClose: () => {
    console.log('Modal closed');
  },
});

Styling

DocSearch comes with default styles via @docsearch/css. You can customize the appearance by:

CSS Variables: Override DocSearch’s CSS custom properties
Custom Classes: Target DocSearch’s class names with your own CSS
Theme Object: Pass a theme configuration (see React documentation)

:root {
  --docsearch-primary-color: #5468ff;
  --docsearch-text-color: #1c1e21;
  --docsearch-spacing: 12px;
  --docsearch-icon-stroke-width: 1.4;
  --docsearch-highlight-color: var(--docsearch-primary-color);
  --docsearch-muted-color: #969faf;
  --docsearch-container-background: rgba(101, 108, 133, 0.8);
  --docsearch-modal-background: #f5f6f7;
}

Next Steps

Configuration

Learn about all available configuration options

Styling

Customize the appearance of your search

Ask AI

Enable AI-powered search assistance

API Reference

Explore the complete API documentation

Get Started

Installation

Core Concepts

Guides

Advanced

JavaScript Installation

Installation

CDN Installation

Basic Setup

Complete Example

API Reference

docsearch(props)

Parameters

Return Value

Programmatic Control

Lifecycle Callbacks

Styling

Next Steps

Configuration

Styling

Ask AI

API Reference

​Installation

​CDN Installation

​Basic Setup

​Complete Example

​API Reference

​docsearch(props)

​Parameters

​Return Value

​Programmatic Control

​Lifecycle Callbacks

​Styling

​Next Steps

Configuration

Styling

Ask AI

API Reference

Installation

CDN Installation

Basic Setup

Complete Example

API Reference

docsearch(props)

Parameters

Return Value

Programmatic Control

Lifecycle Callbacks

Styling

Next Steps