Customization

Learn how to customize DocSearch behavior, appearance, and search results

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

Filter results by version

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

Sort results by custom priority

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

Add custom metadata to results

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>
`}

Results Footer Component

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.