Skip to main content
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

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.ElementSupports 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 | nullSupports 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;
}>;

Build docs developers (and LLMs) love

Get started for freeTalk to us