Skip to main content
DocSearch provides a native React component that integrates seamlessly with React applications. The component is built with React hooks and supports React 16.8+.

​
Installation

Install the @docsearch/react package using your preferred package manager: 
npm install @docsearch/react
The package requires React >= 16.8.0 and React DOM >= 16.8.0 as peer dependencies.

​
CDN Installation

For quick prototyping, you can load DocSearch from a CDN: 
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@4" />
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@4"></script>

​
Basic Setup

1

Import the DocSearch component

Import the DocSearch component and CSS styles:
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';
2

Add DocSearch to your component

Render the DocSearch component with your Algolia credentials:
function App() {
  return (
    <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 example with typical configuration:
App.jsx
import React from 'react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  return (
    <div className="App">
      <header>
        <nav>
          <div className="logo">My Docs</div>
          <DocSearch
            appId="YOUR_APP_ID"
            apiKey="YOUR_SEARCH_API_KEY"
            indexName="YOUR_INDEX_NAME"
            placeholder="Search documentation"
          />
        </nav>
      </header>
      <main>
        {/* Your content */}
      </main>
    </div>
  );
}

export default App;

​
API Reference

​
DocSearch Component

The main React component for rendering DocSearch.

​
Props

​
appId
string
required
Your Algolia application ID.
​
apiKey
string
required
Your Algolia Search API key (public, search-only key).
​
indexName
string
The name of your Algolia index to search.
The indexName prop is deprecated. Use the indices prop instead for multi-index support.
​
indices
Array<DocSearchIndex | string>
List of indices to search. Each item can be a string (index name) or an object with name and optional searchParameters.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    { name: 'docs_v1', searchParameters: { facetFilters: ['version:1.0'] } },
    { name: 'docs_v2', searchParameters: { facetFilters: ['version:2.0'] } },
    'blog'
  ]}
/>
​
placeholder
string
Placeholder text for the search input. Defaults to “Search docs”.
​
searchParameters
SearchParamsObject
Additional Algolia search parameters to apply to all queries.
The searchParameters prop is deprecated. Use the indices prop with per-index parameters instead.
​
maxResultsPerGroup
number
Maximum number of results to show per category. Defaults to 5.
​
transformItems
(items: DocSearchHit[]) => DocSearchHit[]
Hook to transform search results before rendering.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  transformItems={(items) => {
    return items.map(item => ({
      ...item,
      url: item.url.replace('https://example.com', '')
    }));
  }}
/>
​
hitComponent
React.Component
Custom component to render individual search results.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  hitComponent={({ hit, children }) => (
    <a href={hit.url} className="custom-hit">
      {children}
    </a>
  )}
/>
​
resultsFooterComponent
React.Component
Custom component rendered at the bottom of the results panel.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  resultsFooterComponent={({ state }) => (
    <div className="results-footer">
      Found {state.collections.length} results
    </div>
  )}
/>
​
transformSearchClient
(searchClient: DocSearchTransformClient) => DocSearchTransformClient
Hook to wrap or modify the Algolia search client.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  transformSearchClient={(searchClient) => {
    searchClient.addAlgoliaAgent('my-app', '1.0.0');
    return searchClient;
  }}
/>
​
navigator
object
Custom navigator for controlling link navigation. Useful for client-side routing.
// React Router example
import { useNavigate } from 'react-router-dom';

function SearchComponent() {
  const navigate = useNavigate();
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indexName="YOUR_INDEX_NAME"
      navigator={{
        navigate({ itemUrl }) {
          navigate(itemUrl);
        }
      }}
    />
  );
}
​
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.
​
translations
DocSearchTranslations
Localized strings for the button and modal UI.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  translations={{
    button: {
      buttonText: 'Buscar',
      buttonAriaLabel: 'Buscar documentación'
    },
    modal: {
      searchBox: {
        resetButtonTitle: 'Borrar búsqueda',
        cancelButtonText: 'Cancelar'
      }
    }
  }}
/>
​
getMissingResultsUrl
({ query: string }) => string
Returns a URL to report missing results for a given query.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  getMissingResultsUrl={({ query }) => 
    `https://github.com/myorg/docs/issues/new?title=Missing results for "${query}"`
  }
/>
​
insights
object
Algolia Insights client integration for analytics.
import aa from 'search-insights';

aa('init', {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY'
});

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  insights={true}
/>
​
theme
DocSearchTheme
Theme overrides for customizing the appearance.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  theme={{
    primaryColor: '#5468ff',
    backgroundColor: '#f5f6f7',
    textColor: '#1c1e21'
  }}
/>
​
portalContainer
DocumentFragment | Element
The container element where the modal should be portaled. Defaults to document.body.
​
keyboardShortcuts
DocSearchModalShortcuts
Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': true,
    '/': false  // Disable forward slash shortcut
  }}
/>
​
askAi
DocSearchAskAi | string
Configuration for Ask AI mode. Pass an assistant ID string or a full configuration object.
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  askAi={{
    assistantId: 'YOUR_ASSISTANT_ID',
    suggestedQuestions: true,
    searchParameters: {
      facetFilters: ['version:2.0']
    }
  }}
/>

​
Using Refs

You can access DocSearch methods using a ref: 
import React, { useRef } from 'react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  const searchRef = useRef(null);
  
  const openSearch = () => {
    searchRef.current?.open();
  };
  
  const openAskAi = () => {
    searchRef.current?.openAskAi({ query: 'How do I get started?' });
  };
  
  return (
    <div>
      <button onClick={openSearch}>Open Search</button>
      <button onClick={openAskAi}>Ask AI</button>
      
      <DocSearch
        ref={searchRef}
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
      />
    </div>
  );
}

​
Ref Methods

​
open
() => void
Opens the search modal programmatically.
​
close
() => void
Closes the search modal programmatically.
​
openAskAi
(initialMessage?: InitialAskAiMessage) => void
Opens Ask AI mode with an optional pre-filled message.
searchRef.current?.openAskAi({ 
  query: 'How do I configure search?',
  messageId: 'msg_123' 
});
​
isOpen
boolean
Returns true if the modal is currently open.

​
Modular Components

DocSearch also exports individual components for advanced use cases:

​
DocSearchButton

The search button component without the modal: 
import { DocSearchButton } from '@docsearch/react/button';

function CustomSearch() {
  return (
    <DocSearchButton
      translations={{
        buttonText: 'Search docs',
        buttonAriaLabel: 'Search documentation'
      }}
      onClick={() => {
        console.log('Search button clicked');
      }}
    />
  );
}

​
DocSearchModal

The search modal component without the button: 
import { useState } from 'react';
import { DocSearchModal } from '@docsearch/react/modal';
import '@docsearch/react/style';

function CustomSearch() {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <>
      <button onClick={() => setIsOpen(true)}>Search</button>
      
      {isOpen && (
        <DocSearchModal
          appId="YOUR_APP_ID"
          apiKey="YOUR_SEARCH_API_KEY"
          indexName="YOUR_INDEX_NAME"
          initialScrollY={window.scrollY}
          onClose={() => setIsOpen(false)}
        />
      )}
    </>
  );
}

​
useDocSearchKeyboardEvents

Hook for handling keyboard shortcuts: 
import { useRef, useState } from 'react';
import { useDocSearchKeyboardEvents } from '@docsearch/react/useDocSearchKeyboardEvents';

function CustomSearch() {
  const [isOpen, setIsOpen] = useState(false);
  const buttonRef = useRef(null);
  
  useDocSearchKeyboardEvents({
    isOpen,
    onOpen: () => setIsOpen(true),
    onClose: () => setIsOpen(false),
    searchButtonRef: buttonRef
  });
  
  return (
    <button ref={buttonRef} onClick={() => setIsOpen(true)}>
      Search
    </button>
  );
}

​
TypeScript Support

DocSearch is written in TypeScript and includes full type definitions: 
import type { DocSearchProps, DocSearchHit } from '@docsearch/react';
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

const searchConfig: DocSearchProps = {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_API_KEY',
  indexName: 'YOUR_INDEX_NAME',
  transformItems: (items: DocSearchHit[]) => {
    return items.map(item => ({
      ...item,
      url: new URL(item.url, window.location.origin).href
    }));
  }
};

function App() {
  return <DocSearch {...searchConfig} />;
}

​
Styling

DocSearch comes with default styles. You can customize the appearance using:

​
CSS Variables

: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;
}

​
Theme Prop

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  theme={{
    primaryColor: '#5468ff',
    backgroundColor: '#ffffff',
    textColor: '#1c1e21',
    spacing: 12
  }}
/>

​
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