Skip to main content
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

​
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

1

Import DocSearch and styles

Import the docsearch function and CSS styles in your application:
import docsearch from '@docsearch/js';
import '@docsearch/css';
2

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

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

​
container
string | HTMLElement
required
The container for your DocSearch component. Can be a CSS selector string or an HTMLElement.
​
appId
string
required
Your Algolia application ID.
​
apiKey
string
required
Your Algolia Search API key (public, search-only key).
​
indexName
string
required
The name of your Algolia index to search.
​
placeholder
string
Placeholder text for the search input. Defaults to “Search docs”.
​
searchParameters
object
Additional Algolia search parameters to apply to all queries.
searchParameters: {
  hitsPerPage: 10,
  facetFilters: ['version:1.0']
}
​
transformItems
function
Hook to transform search results before rendering.
transformItems: (items) => {
  return items.map(item => ({
    ...item,
    url: item.url.replace('https://example.com', '')
  }));
}
​
hitComponent
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>`;
}
​
resultsFooterComponent
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>`;
}
​
transformSearchClient
function
Hook to wrap or modify the Algolia search client.
transformSearchClient: (searchClient) => {
  searchClient.addAlgoliaAgent('my-app', '1.0.0');
  return searchClient;
}
​
maxResultsPerGroup
number
Maximum number of results to show per category. Defaults to 5.
​
disableUserPersonalization
boolean
Disable storage and display of recent and favorite searches. Defaults to false.
​
initialQuery
string
Query string to prefill when opening the search modal.

​
Return Value

The docsearch() function returns a DocSearchInstance object with the following methods:
​
isReady
boolean
Returns true once the component is mounted and ready.
​
isOpen
boolean
Returns true if the modal is currently open.
​
open
function
Opens the search modal programmatically.
​
close
function
Closes the search modal programmatically.
​
openAskAi
function
Opens Ask AI mode in the modal.
search.openAskAi({ query: 'How do I get started?' });
​
destroy
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:
  1. CSS Variables: Override DocSearch’s CSS custom properties
  2. Custom Classes: Target DocSearch’s class names with your own CSS
  3. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us