DocSearchProps

Configuration interface for the DocSearch component

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.

Single 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.

Simple Configuration

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

Example

<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.

Example

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

Example

<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.

Example

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

Example

<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.

Example

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

initialQuery · string

Query string to prefill when opening the modal.

Example

<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.

Example

<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.

Filter Results

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

JSX Template

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

Example

<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.

Add Custom Headers

<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.

Next.js Router

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.

Example

<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

Example

<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

Example

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

Complete Example

Full Configuration

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