Skip to main content
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
interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}

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

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

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

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

<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

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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us