React Installation

Install and configure DocSearch in React applications

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

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