DocSearch

Main React component for DocSearch

The DocSearch component is the primary React component for integrating Algolia DocSearch into your application. It renders a search button and modal interface for searching documentation.

Import

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

Usage

Basic Usage

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

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

Props

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.

indices · Array<DocSearchIndex | string>

List of indices and optional search parameters to be used for search.

Each item can be a string (index name) or an object with:

• name (string): Index name
• searchParameters (SearchParamsObject): Optional search parameters for this index

askAi · DocSearchAskAi | string

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

When provided as an object, supports:

• assistantId (string, required): The assistant ID to use
• indexName (string): Index name for Ask AI (defaults to main index)
• apiKey (string): API key for Ask AI (defaults to main apiKey)
• appId (string): App ID for Ask AI (defaults to main appId)
• suggestedQuestions (boolean): Enable suggested questions display
• searchParameters (AskAiSearchParameters): Search parameters for AI context retrieval
• agentStudio (boolean): Experimental Agent Studio backend support

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., @docsearch/sidepanel-js) without flicker.

theme · 'light' | 'dark'

Theme overrides applied to the modal and related components.

placeholder · string

Placeholder text for the search input.

searchParameters · SearchParamsObject · deprecated

Additional Algolia search parameters to merge into each query.

Deprecated: Use indices property instead.

maxResultsPerGroup · number

Maximum number of hits to display per source/group.

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

Hook to post-process hits before rendering. Receives an array of hits and should return the transformed array.

hitComponent · function

Custom component to render an individual hit.

Signature: (props: { hit: InternalDocSearchHit | StoredDocSearchHit; children: React.ReactNode }, helpers?: { html: (template: TemplateStringsArray, ...values: any[]) => any }) => JSX.Element

Supports multiple template patterns:

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

resultsFooterComponent · function

Custom component rendered at the bottom of the results panel.

Signature: (props: { state: AutocompleteState<InternalDocSearchHit> }, helpers?: { html: (template: TemplateStringsArray, ...values: any[]) => any }) => JSX.Element | null

Supports the same template patterns as hitComponent.

transformSearchClient · (searchClient: DocSearchTransformClient) => DocSearchTransformClient

Hook to wrap or modify the Algolia search client. Use this to add custom headers, middleware, or other client modifications.

disableUserPersonalization · boolean · default: "false"

Disable storage and usage of recent and favorite searches.

initialQuery · string

Query string to prefill when opening the modal.

navigator · AutocompleteOptions['navigator']

Custom navigator for controlling link navigation. Useful for client-side routing.

translations · DocSearchTranslations

Localized strings for the button and modal UI.

Object with optional properties:

• button (ButtonTranslations): Button translations
• modal (ModalTranslations): Modal translations

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

Builds a URL to report missing results for a given query. The returned URL is used in the “no results” screen.

insights · AutocompleteOptions['insights']

Insights client integration options to send analytics events.

portalContainer · DocumentFragment | Element

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

recentSearchesLimit · number · default: "7"

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

recentSearchesWithFavoritesLimit · number · default: "4"

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

keyboardShortcuts · DocSearchModalShortcuts · default: "{ 'Ctrl/Cmd+K': true, '/': true }"

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

Object with optional properties:

• 'Ctrl/Cmd+K' (boolean): Enable/disable Ctrl/Cmd+K shortcut
• '/' (boolean): Enable/disable forward slash shortcut

Ref Methods

When using React.forwardRef, the component exposes a DocSearchRef object with methods for programmatic control:

openModal · function

Opens the search modal programmatically.

closeModal · function

Closes the search modal programmatically.

Example with Ref

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

function App() {
  const searchRef = useRef(null);

  return (
    <>
      <button onClick={() => searchRef.current?.openModal()}>
        Open Search
      </button>
      <DocSearch
        ref={searchRef}
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
      />
    </>
  );
}

Types

DocSearchIndex

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

DocSearchAskAi

type DocSearchAskAi = {
  assistantId: string;
  indexName?: string;
  apiKey?: string;
  appId?: string;
  suggestedQuestions?: boolean;
  agentStudio?: boolean;
  searchParameters?: AskAiSearchParameters | AgentStudioSearchParameters;
};

DocSearchTranslations

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