> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```jsx theme={null}
import { DocSearch } from '@docsearch/react';
```

## Usage

<CodeGroup>
  ```jsx Basic Usage theme={null}
  import { DocSearch } from '@docsearch/react';

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

  ```jsx With Multiple Indices theme={null}
  import { DocSearch } from '@docsearch/react';

  function App() {
    return (
      <DocSearch
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indices={[
          'primary_docs',
          {
            name: 'api_docs',
            searchParameters: {
              filters: 'version:latest'
            }
          }
        ]}
      />
    );
  }
  ```

  ```jsx With Ask AI theme={null}
  import { DocSearch } from '@docsearch/react';

  function App() {
    return (
      <DocSearch
        appId="YOUR_APP_ID"
        apiKey="YOUR_SEARCH_API_KEY"
        indexName="YOUR_INDEX_NAME"
        askAi={{
          assistantId: "YOUR_ASSISTANT_ID",
          suggestedQuestions: true
        }}
      />
    );
  }
  ```
</CodeGroup>

## Props

<ParamField path="appId" type="string" required>
  Algolia application ID used by the search client.
</ParamField>

<ParamField path="apiKey" type="string" required>
  Public API key with search permissions for the index.
</ParamField>

<ParamField path="indexName" type="string" deprecated>
  Name of the Algolia index to query.

  **Deprecated:** Use `indices` property instead.
</ParamField>

<ParamField path="indices" type="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
</ParamField>

<ParamField path="askAi" type="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
</ParamField>

<ParamField path="interceptAskAiEvent" type="(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.
</ParamField>

<ParamField path="theme" type="'light' | 'dark'">
  Theme overrides applied to the modal and related components.
</ParamField>

<ParamField path="placeholder" type="string">
  Placeholder text for the search input.
</ParamField>

<ParamField path="searchParameters" type="SearchParamsObject" deprecated>
  Additional Algolia search parameters to merge into each query.

  **Deprecated:** Use `indices` property instead.
</ParamField>

<ParamField path="maxResultsPerGroup" type="number">
  Maximum number of hits to display per source/group.
</ParamField>

<ParamField path="transformItems" type="(items: DocSearchHit[]) => DocSearchHit[]">
  Hook to post-process hits before rendering. Receives an array of hits and should return the transformed array.
</ParamField>

<ParamField path="hitComponent" type="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\`<div>...</div>\`\`
  * JSX templates: `(props) => <div>...</div>`
  * Function-based templates
</ParamField>

<ParamField path="resultsFooterComponent" type="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`.
</ParamField>

<ParamField path="transformSearchClient" type="(searchClient: DocSearchTransformClient) => DocSearchTransformClient">
  Hook to wrap or modify the Algolia search client. Use this to add custom headers, middleware, or other client modifications.
</ParamField>

<ParamField path="disableUserPersonalization" type="boolean" default="false">
  Disable storage and usage of recent and favorite searches.
</ParamField>

<ParamField path="initialQuery" type="string">
  Query string to prefill when opening the modal.
</ParamField>

<ParamField path="navigator" type="AutocompleteOptions['navigator']">
  Custom navigator for controlling link navigation. Useful for client-side routing.
</ParamField>

<ParamField path="translations" type="DocSearchTranslations">
  Localized strings for the button and modal UI.

  Object with optional properties:

  * `button` (ButtonTranslations): Button translations
  * `modal` (ModalTranslations): Modal translations
</ParamField>

<ParamField path="getMissingResultsUrl" type="({ 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.
</ParamField>

<ParamField path="insights" type="AutocompleteOptions['insights']">
  Insights client integration options to send analytics events.
</ParamField>

<ParamField path="portalContainer" type="DocumentFragment | Element">
  The container element where the modal should be portaled to. Defaults to `document.body`.
</ParamField>

<ParamField path="recentSearchesLimit" type="number" default="7">
  Limit of how many recent searches should be saved/displayed.
</ParamField>

<ParamField path="recentSearchesWithFavoritesLimit" type="number" default="4">
  Limit of how many recent searches should be saved/displayed when there are favorited searches.
</ParamField>

<ParamField path="keyboardShortcuts" type="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
</ParamField>

## Ref Methods

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

<ResponseField name="openModal" type="function">
  Opens the search modal programmatically.
</ResponseField>

<ResponseField name="closeModal" type="function">
  Closes the search modal programmatically.
</ResponseField>

## Example with Ref

```jsx theme={null}
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

```typescript theme={null}
interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}
```

### DocSearchAskAi

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

### DocSearchTranslations

```typescript theme={null}
type DocSearchTranslations = Partial<{
  button: ButtonTranslations;
  modal: ModalTranslations;
}>;
```