Configuration

Configure DocSearch with these options to customize search behavior, appearance, and functionality.

DocSearch accepts configuration options through the DocSearchProps interface. Pass these options to the DocSearch component to customize its behavior.

Required Options

appId · string · required

Algolia application ID used by the search client.

apiKey · string · required

Public API key with search permissions for the index.

indexName · string · deprecated

Name of the Algolia index to query.

Deprecated: Use indices property instead. This will be removed in a future version.

indices · Array<DocSearchIndex | string>

List of indices and optional search parameters to be used for search. Each item can be:

• A string (index name)
• A DocSearchIndex object with name and optional searchParameters

DocSearchIndex Interface

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

Simple Usage

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indices={["docs", "blog"]}
/>

Ask AI Configuration

askAi · DocSearchAskAi | string

Configuration to enable Ask AI mode. Pass a string assistant ID or a full config object.

DocSearchAskAi Interface

type DocSearchAskAi = {
  // The assistant ID to use for the ask AI feature
  assistantId: string;
  
  // Optional: Index name for AI search (defaults to main index)
  indexName?: string;
  
  // Optional: API key for AI (defaults to main apiKey)
  apiKey?: string;
  
  // Optional: App ID for AI (defaults to main appId)
  appId?: string;
  
  // Enable suggested questions on new conversation screen
  // Default: false
  suggestedQuestions?: boolean;
  
  // Search parameters for the AI feature
  searchParameters?: AskAiSearchParameters;
  
  // Experimental: Use Agent Studio as chat backend
  agentStudio?: boolean;
};

type AskAiSearchParameters = {
  facetFilters?: string[];
  filters?: string;
  attributesToRetrieve?: string[];
  restrictSearchableAttributes?: string[];
  distinct?: boolean | number | string;
};

Simple Usage

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_API_KEY"
  indexName="docs"
  askAi="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). Useful to route Ask AI into a different UI (e.g., sidepanel) without flicker.

interface InitialAskAiMessage {
  query: string;
  suggestedQuestionId?: string;
  messageId?: string;
}

Search Customization

placeholder · string

Placeholder text for the search input.

<DocSearch
  placeholder="Search documentation..."
/>

searchParameters · SearchParamsObject · deprecated

Additional Algolia search parameters to merge into each query.

Deprecated: Use indices property instead. This will be removed in a future version.

maxResultsPerGroup · number

Maximum number of hits to display per source/group.

<DocSearch
  maxResultsPerGroup={5}
/>

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

Hook to post-process hits before rendering. Useful for filtering, sorting, or modifying search results.

Filter Results

<DocSearch
  transformItems={(items) => {
    return items.filter(item => 
      !item.url.includes('/deprecated/')
    );
  }}
/>

transformSearchClient · (searchClient: DocSearchTransformClient) => DocSearchTransformClient

Hook to wrap or modify the Algolia search client. Useful for adding custom headers, logging, or modifying requests.

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

Add Custom Headers

<DocSearch
  transformSearchClient={(searchClient) => {
    searchClient.transporter.headers = {
      ...searchClient.transporter.headers,
      'X-Custom-Header': 'value'
    };
    return searchClient;
  }}
/>

Custom Components

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

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

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

JSX Template

<DocSearch
  hitComponent={({ hit, children }) => (
    <a href={hit.url} className="custom-hit">
      {children}
      <span className="hit-badge">{hit.type}</span>
    </a>
  )}
/>

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

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

interface ResultsFooterProps {
  state: AutocompleteState<InternalDocSearchHit>;
}

<DocSearch
  resultsFooterComponent={({ state }) => (
    <div className="results-footer">
      Found {state.context.nbHits} results
    </div>
  )}
/>

User Personalization

disableUserPersonalization · boolean · default: false

Disable storage and usage of recent and favorite searches.

<DocSearch
  disableUserPersonalization={true}
/>

recentSearchesLimit · number · default: 7

Limit of how many recent searches should be saved and displayed.

recentSearchesWithFavoritesLimit · number · default: 4

Limit of how many recent searches should be saved and displayed when there are favorited searches.

Navigation & Behavior

initialQuery · string

Query string to prefill when opening the modal.

<DocSearch
  initialQuery="getting started"
/>

navigator · AutocompleteOptions['navigator']

Custom navigator for controlling link navigation. Useful for integrating with client-side routers.

<DocSearch
  navigator={{
    navigate({ itemUrl }) {
      // Use your router instead of default navigation
      router.push(itemUrl);
    }
  }}
/>

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

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

<DocSearch
  getMissingResultsUrl={({ query }) => 
    `https://github.com/myorg/docs/issues/new?title=Missing results for: ${query}`
  }
/>

keyboardShortcuts · DocSearchModalShortcuts

Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.

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

Disable Slash Shortcut

<DocSearch
  keyboardShortcuts={{
    'Ctrl/Cmd+K': true,
    '/': false
  }}
/>

Theming & Display

theme · DocSearchTheme

Theme overrides applied to the modal and related components. Accepts 'dark' or 'light'.

See Theme Options for more details.

<DocSearch
  theme="dark"
/>

translations · DocSearchTranslations

Localized strings for the button and modal UI.

See Translations for all available translation strings.

<DocSearch
  translations={{
    button: {
      buttonText: 'Rechercher',
      buttonAriaLabel: 'Rechercher'
    },
    modal: {
      searchBox: {
        placeholderText: 'Rechercher dans la documentation'
      }
    }
  }}
/>

portalContainer · DocumentFragment | Element

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

<DocSearch
  portalContainer={document.getElementById('modal-root')}
/>

Analytics

insights · AutocompleteOptions['insights']

Insights client integration options to send analytics events.

<DocSearch
  insights={{
    insightsClient: window.aa,
    onItemsChange({ insights, insightsEvents }) {
      const events = insightsEvents.map((event) => ({
        ...event,
        eventName: 'Hits Viewed'
      }));
      insights.viewedObjectIDs(...events);
    }
  }}
/>

Usage Example

Basic Configuration

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

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indexName="docs"
    />
  );
}