DocSearchProps

The DocSearchProps interface defines all configuration options for the DocSearch component. This is the primary interface used to configure search behavior, UI customization, AI features, and user interactions.

Required Properties

appId

string

required

Algolia application ID used by the search client.

apiKey

string

required

Public API key with search permissions for the index. This should be a search-only API key, never your admin API key.

Index Configuration

indexName

string

deprecated

Name of the Algolia index to query.Deprecated: indexName will be removed in a future version. Please use the indices property going forward.

indices

Array<DocSearchIndex | string>

List of indices and optional search parameters to be used for search. This allows querying multiple indices or configuring per-index search parameters.See the indices documentation for more details.

Show DocSearchIndex Type

interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}

name

string

The name of the Algolia index.

searchParameters

SearchParamsObject

Optional Algolia search parameters specific to this index.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={['docs']}
/>

searchParameters

SearchParamsObject

deprecated

Additional Algolia search parameters to merge into each query.Deprecated: searchParameters will be removed in a future version. Please use the indices property going forward.

AI Features

askAi

DocSearchAskAi | string

Configuration or assistant ID to enable Ask AI mode. Pass a string assistant ID for simple configuration, or a full config object for advanced options.See DocSearchAskAi configuration for detailed options.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  askAi="your-assistant-id"
/>

interceptAskAiEvent

(initialMessage: InitialAskAiMessage) => boolean | void

Intercept Ask AI requests (e.g., submitting a prompt or selecting a suggested question).Return true to prevent the default modal Ask AI flow (no toggle, no sendMessage). This is useful to route Ask AI into a different UI (e.g., @docsearch/sidepanel-js) without flicker.

Show InitialAskAiMessage Type

type InitialAskAiMessage = {
  query: string;
  messageId?: string;
  suggestedQuestionId?: string;
};

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  askAi="your-assistant-id"
  interceptAskAiEvent={(initialMessage) => {
    // Route to custom sidepanel
    openCustomSidepanel(initialMessage.query);
    return true; // Prevent default behavior
  }}
/>

UI Customization

theme

DocSearchTheme

Theme overrides applied to the modal and related components.

type DocSearchTheme = 'dark' | 'light';

placeholder

string

Placeholder text for the search input.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  placeholder="Search documentation..."
/>

translations

DocSearchTranslations

Localized strings for the button and modal UI.

Show DocSearchTranslations Type

type DocSearchTranslations = Partial<{
  button: ButtonTranslations;
  modal: ModalTranslations;
}>;

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  translations={{
    button: {
      buttonText: 'Search',
      buttonAriaLabel: 'Search documentation'
    },
    modal: {
      searchBox: {
        resetButtonTitle: 'Clear',
        cancelButtonText: 'Cancel'
      }
    }
  }}
/>

portalContainer

DocumentFragment | Element

The container element where the modal should be portaled to. Defaults to document.body.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  portalContainer={document.getElementById('modal-root')}
/>

keyboardShortcuts

DocSearchModalShortcuts

Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.Default: { 'Ctrl/Cmd+K': true, '/': true }

Show DocSearchModalShortcuts Type

interface DocSearchModalShortcuts {
  'Ctrl/Cmd+K'?: boolean;
  '/'?: boolean;
}

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  keyboardShortcuts={{
    'Ctrl/Cmd+K': true,
    '/': false  // Disable the / shortcut
  }}
/>

Search Behavior

maxResultsPerGroup

number

Maximum number of hits to display per source/group.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  maxResultsPerGroup={8}
/>

initialQuery

string

Query string to prefill when opening the modal.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  initialQuery="getting started"
/>

getMissingResultsUrl

({ query }: { query: string }) => string

Builds a URL to report missing results for a given query.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  getMissingResultsUrl={({ query }) => 
    `https://github.com/your-org/docs/issues/new?title=Missing+results+for+${encodeURIComponent(query)}`
  }
/>

Custom Components

transformItems

(items: DocSearchHit[]) => DocSearchHit[]

Hook to post-process hits before rendering. Use this to filter, sort, or modify search results.See DocSearchHit type for the hit structure.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  transformItems={(items) => 
    items.filter(item => item.type !== 'lvl1')
  }
/>

hitComponent

(props, helpers?) => JSX.Element

Custom component to render an individual hit. Supports multiple template patterns:

HTML strings with html helper: (props, { html }) => html
…
“
JSX templates: (props) => <div>...</div>
Function-based templates: (props) => string | JSX.Element | Function

Show Props Type

{
  hit: InternalDocSearchHit | StoredDocSearchHit;
  children: React.ReactNode;
}

Show Helpers Type

{
  html: (template: TemplateStringsArray, ...values: any[]) => any;
}

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  hitComponent={({ hit, children }) => (
    <a href={hit.url} className="custom-hit">
      <div className="hit-icon">📄</div>
      {children}
    </a>
  )}
/>

resultsFooterComponent

(props, helpers?) => JSX.Element | null

Custom component rendered at the bottom of the results panel. Supports the same template patterns as hitComponent.

Show Props Type

{
  state: AutocompleteState<InternalDocSearchHit>;
}

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  resultsFooterComponent={({ state }) => (
    <div className="results-footer">
      Found {state.collections.reduce((acc, col) => acc + col.items.length, 0)} results
    </div>
  )}
/>

Advanced Configuration

transformSearchClient

(searchClient: DocSearchTransformClient) => DocSearchTransformClient

Hook to wrap or modify the Algolia search client. Useful for adding custom middleware, logging, or request modification.

Show DocSearchTransformClient Type

type DocSearchTransformClient = {
  search: LiteClient['search'];
  addAlgoliaAgent: LiteClient['addAlgoliaAgent'];
  transporter: Pick<LiteClient['transporter'], 'algoliaAgent'>;
};

This is the minimal implementation required for the Algolia search client when using the transformSearchClient option.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  transformSearchClient={(searchClient) => ({
    ...searchClient,
    search(requests) {
      // Add custom headers or modify requests
      return searchClient.search(requests);
    }
  })}
/>

navigator

AutocompleteOptions<InternalDocSearchHit>['navigator']

Custom navigator for controlling link navigation. Use this to integrate with client-side routers or add custom navigation logic.

import { useRouter } from 'next/router';

function Search() {
  const router = useRouter();
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indexName="docs"
      navigator={{
        navigate({ itemUrl }) {
          router.push(itemUrl);
        }
      }}
    />
  );
}

insights

AutocompleteOptions<InternalDocSearchHit>['insights']

Insights client integration options to send analytics events. This allows tracking user interactions with search results.

User Personalization

disableUserPersonalization

boolean

Disable storage and usage of recent and favorite searches.

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  disableUserPersonalization={true}
/>

recentSearchesLimit

number

Limit of how many recent searches should be saved/displayed.Default: 7

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  recentSearchesLimit={10}
/>

recentSearchesWithFavoritesLimit

number

Limit of how many recent searches should be saved/displayed when there are favorited searches.Default: 4

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="docs"
  recentSearchesWithFavoritesLimit={6}
/>

Complete Example

import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function MyApp() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'docs',
          searchParameters: {
            hitsPerPage: 10,
            filters: 'version:latest'
          }
        }
      ]}
      askAi={{
        assistantId: 'your-assistant-id',
        suggestedQuestions: true
      }}
      theme="light"
      placeholder="Search documentation..."
      maxResultsPerGroup={8}
      transformItems={(items) => 
        items.map(item => ({
          ...item,
          url: item.url.replace('http://', 'https://')
        }))
      }
      translations={{
        button: {
          buttonText: 'Search',
          buttonAriaLabel: 'Search documentation'
        }
      }}
      getMissingResultsUrl={({ query }) => 
        `https://github.com/your-org/docs/issues/new?title=Missing+results+for+${encodeURIComponent(query)}`
      }
    />
  );
}

JavaScript API

React API

Configuration

Types

DocSearchProps

DocSearchProps

Required Properties

Index Configuration

AI Features

UI Customization

Search Behavior

Custom Components

Advanced Configuration

User Personalization

Complete Example

Build docs developers (and LLMs) love

JavaScript API

React API

Configuration

Types

​DocSearchProps

​Required Properties

​Index Configuration

​AI Features

​UI Customization

​Search Behavior

​Custom Components

​Advanced Configuration

​User Personalization

​Complete Example

Build docs developers (and LLMs) love

DocSearchProps

Required Properties

Index Configuration

AI Features

UI Customization

Search Behavior

Custom Components

Advanced Configuration

User Personalization

Complete Example