Skip to main content
DocSearch provides extensive customization options to tailor the search experience to your documentation site’s needs.

​
Placeholder Text

Customize the search input placeholder text to guide users: 
import { DocSearch } from '@docsearch/react';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      placeholder="Search documentation..."
    />
  );
}
The placeholder text automatically adapts when Ask AI features are enabled:
  • Default: Uses your custom placeholder prop or “Search docs”
  • Ask AI enabled: Changes to “Search docs or ask AI a question”
  • In Ask AI mode: Shows “Ask another question…”

​
Transform Items

The transformItems function allows you to modify search results before they’re displayed. This is useful for filtering, sorting, or enhancing results. 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  transformItems={(items) => {
    // Filter out deprecated pages
    return items.filter((item) => !item.url.includes('/deprecated/'));
  }}
/>

​
Common Use Cases

transformItems={(items) => {
  const currentVersion = 'v2';
  return items.filter((item) => 
    item.hierarchy?.lvl0?.includes(currentVersion)
  );
}}

transformItems={(items) => {
  return items.sort((a, b) => {
    // Prioritize "Getting Started" pages
    const aIsGettingStarted = a.hierarchy?.lvl1?.includes('Getting Started');
    const bIsGettingStarted = b.hierarchy?.lvl1?.includes('Getting Started');
    
    if (aIsGettingStarted && !bIsGettingStarted) return -1;
    if (!aIsGettingStarted && bIsGettingStarted) return 1;
    return 0;
  });
}}

transformItems={(items) => {
  return items.map((item) => ({
    ...item,
    // Add custom badge based on content type
    customBadge: item.type === 'lvl1' ? 'Guide' : 'Reference',
  }));
}}

​
Maximum Results Per Group

Control how many results are displayed per section: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  maxResultsPerGroup={10}
/>
The default value is determined by the Algolia search configuration. Setting this value will override the default behavior.

​
Custom Hit Component

Customize how individual search results are rendered: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  hitComponent={({ hit, children }) => (
    <div className="custom-hit">
      {children}
      {hit.type === 'lvl1' && (
        <span className="badge">Guide</span>
      )}
    </div>
  )}
/>

​
Using HTML Template Syntax

You can also use HTML template strings: 
hitComponent={(props, { html }) => html`
  <div class="custom-hit">
    <h4>${props.hit.hierarchy.lvl1}</h4>
    <p>${props.hit.content}</p>
  </div>
`}
Add custom content at the bottom of search results: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  resultsFooterComponent={({ state }) => (
    <div className="custom-footer">
      <p>Found {state.collections.length} results</p>
      <a href="https://github.com/algolia/docsearch/issues">Can't find what you're looking for?</a>
    </div>
  )}
/>

​
Search Parameters

Pass additional Algolia search parameters to customize the search behavior: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indices={[
    {
      name: 'YOUR_INDEX_NAME',
      searchParameters: {
        hitsPerPage: 20,
        attributesToRetrieve: [
          'hierarchy.lvl0',
          'hierarchy.lvl1',
          'hierarchy.lvl2',
          'content',
          'url',
        ],
        attributesToSnippet: ['content:20'],
        distinct: 1,
        facetFilters: ['version:latest'],
      },
    },
  ]}
/>
The indices property replaces the deprecated indexName and searchParameters props, allowing you to search multiple indices with different configurations.

​
Multiple Indices

Search across multiple documentation indices: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indices={[
    'docs_v2',
    {
      name: 'docs_v1',
      searchParameters: {
        facetFilters: ['version:v1'],
      },
    },
    'blog',
  ]}
/>

​
Transform Search Client

Modify the Algolia search client before it’s used: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  transformSearchClient={(searchClient) => {
    // Add custom headers or modify requests
    return {
      ...searchClient,
      search(requests) {
        // Log search queries for analytics
        console.log('Search requests:', requests);
        return searchClient.search(requests);
      },
    };
  }}
/>

​
Initial Query

Pre-fill the search input with an initial query: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  initialQuery="getting started"
/>

​
Custom Navigator

Control navigation behavior when users select search results: 
import { useNavigate } from 'react-router-dom';

function App() {
  const navigate = useNavigate();
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_API_KEY"
      indexName="YOUR_INDEX_NAME"
      navigator={{
        navigate({ itemUrl }) {
          // Use React Router instead of default navigation
          navigate(itemUrl);
        },
      }}
    />
  );
}

​
Missing Results URL

Provide a feedback mechanism for queries with no results: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  getMissingResultsUrl={({ query }) => {
    return `https://github.com/your-org/docs/issues/new?title=Missing results for "${query}"`;
  }}
/>
When users search for something with no results, they’ll see a link to report the missing content.

​
Portal Container

Specify where the search modal should be rendered in the DOM: 
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="YOUR_INDEX_NAME"
  portalContainer={document.getElementById('modal-root')}
/>
By default, the modal is rendered into document.body.

Build docs developers (and LLMs) love

Get started for freeTalk to us