Skip to main content

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