Skip to main content
Version: Stable (v4.x)

API Reference

container​

type: string | HTMLElement | required

The container for the DocSearch search box. You can either pass a CSS selector or an Element. If there are several containers matching the selector, DocSearch picks up the first one.

environment​

type: typeof window | default: window | optional

The environment in which your application is running.

This is useful if you’re using DocSearch in a different context than window.

appId​

type: string | required

Your Algolia application ID.

apiKey​

type: string | required

Your Algolia Search API key.

indices​

type: Array<string | DocSearchIndex>

The list of indices and their optional searchParameters to be used for keyword search.

Algolia Search Parameters

tip

The ordering matters in the list, as results are ordered based on indices order.

While indexName is in deprecation, it is required to pass either indices or indexName. Not passing either will result in an Error being thrown.

docsearch({
  // ...
  indices: ['YOUR_ALGOLIA_INDEX'],
  // ...
});

in case you want to use custom searchParameters for the index

docsearch({
  // ...
  indices: [
    {
      name: 'YOUR_ALGOLIA_INDEX',
      searchParameters: {
        facetFilters: ['language:en'],
        // ...
      },
    },
  ],
  // ...
});

indexName​

type: string | deprecated

Deprecation warning

indexName is currently being planned for deprecation. The new recommended property to use is indices.

Your Algolia index name.

While indexName is in deprecation, it is required to pass either indices or indexName. Not passing either will result in an Error being thrown.

placeholder​

type: string | default: "Search docs" | optional

The placeholder of the input of the DocSearch pop-up modal. Note: If you add a placeholder it will replace the dynamic placeholder based on askAi, It would be better to edit translations

askAi​

type: AskAiObject | string | optional

Your Algolia Assistant ID.

docsearch({
  // ...
  askAi: 'YOUR_ALGOLIA_ASSISTANT_ID',
  // ...
});

or if you want to use different credentials for askAi and add search parameters

docsearch({
  // ...
  askAi: {
    indexName: 'ANOTHER_INDEX_NAME',
    apiKey: 'ANOTHER_SEARCH_API_KEY',
    appId: 'ANOTHER_APP_ID',
    assistantId: 'YOUR_ALGOLIA_ASSISTANT_ID',
    searchParameters: {
      // Filtering parameters
      facetFilters: ['language:en', 'version:latest'],
      filters: 'type:content AND language:en',

      // Content control parameters
      attributesToRetrieve: ['title', 'content', 'url'],
      restrictSearchableAttributes: ['title', 'content'],

      // Deduplication
      distinct: true,
    },

    // Enables/disables showing suggested questions on Ask AI's new conversation screen
    suggestedQuestions: true,
  },
  // ...
});
Ask AI supports these essential search parameters for optimal performance:
  • Filtering: facetFilters: ['type:content'] - Filter by language, version, or content type
  • Complex filtering: filters: 'type:content AND language:en' - Apply complex filtering rules
  • Content control: attributesToRetrieve: ['title', 'content', 'url'] - Control which attributes are retrieved
  • Search scope: restrictSearchableAttributes: ['title', 'content'] - Limit search to specific fields
  • Deduplication: distinct: true - Remove duplicate results

These parameters provide the essential functionality for Ask AI while keeping the API simple and focused.

searchParameters​

type: SearchParameters | optional | deprecated

Deprecation warning

searchParameters is currently being planned for deprecation. The new recommended property to use is indices.

The Algolia Search Parameters.

transformItems​

type: function | default: items => items | optional

Receives the items from the search response, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.

docsearch({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      content: item.content.toUpperCase(),
    }));
  },
});

hitComponent​

type: ({ hit, children }, { html }) => JSX.Element | string | Function | default: Hit | optional

The component to display each item. Supports template patterns:

  • HTML strings with html helper (recommended for JS CDN): ({ hit, children }, { html }) => html...
  • JSX templates (for React/Preact): ({ hit, children }) => <div>...</div>
  • Function-based templates: (props) => string | JSX.Element | Function

You get access to the hit object which contains all the data for the search result, and children which is the default rendered content.

See the default implementation.

docsearch({
  // ...
  hitComponent({ hit, children }, { html }) {
    // Using HTML strings with html helper
    return html`
      <a href="${hit.url}" class="custom-hit-class">
        <div class="hit-icon">🔍</div>
        <div class="hit-content">${children}</div>
      </a>
    `;
  },
});

transformSearchClient​

type: function | default: DocSearchTransformClient => DocSearchTransformClient | optional

Useful for transforming the Algolia Search Client, for example to debounce search queries

disableUserPersonalization​

type: boolean | default: false | optional

Disable saving recent searches and favorites to the local storage.

initialQuery​

type: string | optional

The search input initial query.

type: Navigator | optional

An implementation of Algolia Autocomplete’s Navigator API to redirect the user when opening a link.

Learn more on the Navigator API documentation.

translations​

type: Partial<DocSearchTranslations> | default: docSearchTranslations | optional

Allow translations of any raw text and aria-labels present in the DocSearch button or modal components.

docSearchTranslations
const translations: DocSearchTranslations = {
  button: {
    buttonText: 'Search',
    buttonAriaLabel: 'Search',
  },
  modal: {
    searchBox: {
      clearButtonTitle: 'Clear',
      clearButtonAriaLabel: 'Clear the query',
      closeButtonText: 'Close',
      closeButtonAriaLabel: 'Close',
      placeholderText: undefined, // fallback: 'Search docs' or 'Search docs or ask AI a question'
      placeholderTextAskAi: undefined, // fallback: 'Ask another question...'
      placeholderTextAskAiStreaming: 'Answering...',
      // can only be one of the following
      // https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/enterkeyhint#value
      enterKeyHint: 'search',
      enterKeyHintAskAi: 'enter',
      searchInputLabel: 'Search',
      backToKeywordSearchButtonText: 'Back to keyword search',
      backToKeywordSearchButtonAriaLabel: 'Back to keyword search',
      newConversationPlaceholder: 'Ask a question',
      conversationHistoryTitle: 'My conversation history',
      startNewConversationText: 'Start a new conversation',
      viewConversationHistoryText: 'Conversation history'
    },
    startScreen: {
      recentSearchesTitle: 'Recent',
      noRecentSearchesText: 'No recent searches',
      saveRecentSearchButtonTitle: 'Save this search',
      removeRecentSearchButtonTitle: 'Remove this search from history',
      favoriteSearchesTitle: 'Favorite',
      removeFavoriteSearchButtonTitle: 'Remove this search from favorites',
      recentConversationsTitle: 'Recent conversations',
      removeRecentConversationButtonTitle:
        'Remove this conversation from history',
    },
    errorScreen: {
      titleText: 'Unable to fetch results',
      helpText: 'You might want to check your network connection.',
    },
    noResultsScreen: {
      noResultsText: 'No results found for',
      suggestedQueryText: 'Try searching for',
      reportMissingResultsText: 'Believe this query should return results?',
      reportMissingResultsLinkText: 'Let us know.',
    },
    resultsScreen: {
      askAiPlaceholder: 'Ask AI: ',
      noResultsAskAiPlaceholder: 'Didn't find it in the docs? Ask AI to help: ',
    },
    askAiScreen: {
      disclaimerText:
        'Answers are generated with AI which can make mistakes. Verify responses.',
      relatedSourcesText: 'Related sources',
      thinkingText: 'Thinking...',
      copyButtonText: 'Copy',
      copyButtonCopiedText: 'Copied!',
      copyButtonTitle: 'Copy',
      likeButtonTitle: 'Like',
      dislikeButtonTitle: 'Dislike',
      thanksForFeedbackText: 'Thanks for your feedback!',
      preToolCallText: 'Searching...',
      duringToolCallText: 'Searching for ',
      afterToolCallText: 'Searched for',
      // If provided, these override the default rendering of aggregated tool calls:
      aggregatedToolCallNode: undefined, // (queries: string[], onSearchQueryClick: (query: string) => void) => React.ReactNode
      aggregatedToolCallText: undefined, // (queries: string[]) => { before?: string; separator?: string; lastSeparator?: string; after?: string }
      // Text to show when user has stopped streaming a message
      stoppedStreamingText: 'You stopped this response',
    },
    footer: {
      selectText: 'Select',
      submitQuestionText: 'Submit question',
      selectKeyAriaLabel: 'Enter key',
      navigateText: 'Navigate',
      navigateUpKeyAriaLabel: 'Arrow up',
      navigateDownKeyAriaLabel: 'Arrow down',
      closeText: 'Close',
      backToSearchText: 'Back to search',
      closeKeyAriaLabel: 'Escape key',
      poweredByText: 'Powered by',
    },
    newConversation: {
      newConversationTitle: 'How can I help you today?',
      newConversationDescription: 'I search through your documentation to help you find setup guides, feature details and troubleshooting tips, fast.'
    }
  },
};

getMissingResultsUrl​

type: ({ query: string }) => string | optional

Function to return the URL of your documentation repository.

docsearch({
  // ...
  getMissingResultsUrl({ query }) {
    return `https://github.com/algolia/docsearch/issues/new?title=${query}`;
  },
});

When provided, an informative message wrapped with your link will be displayed on no results searches. The default text can be changed using the translations property.

No results screen with informative message

keyboardShortcuts​

type: KeyboardShortcuts | optional

Configuration for keyboard shortcuts that trigger the search modal.

Default behavior:​

  • Ctrl/Cmd+K - Opens and closes the search modal
  • / - Opens the search modal (doesn't close)

Interface:​

interface KeyboardShortcuts {
  'Ctrl/Cmd+K'?: boolean; // default: true
  '/'?: boolean; // default: true
}
// Default - all shortcuts enabled
docsearch({
  // ...
});

// Disable slash shortcut
docsearch({
  // ...
  keyboardShortcuts: { '/': false },
});

// Disable Ctrl/Cmd+K shortcut (also hides button hint)
docsearch({
  // ...
  keyboardShortcuts: { 'Ctrl/Cmd+K': false },
});

// Disable all keyboard shortcuts
docsearch({
  // ...
  keyboardShortcuts: { 'Ctrl/Cmd+K': false, '/': false },
});
Keyboard Shortcut Behavior
  • Ctrl/Cmd+K: Toggle shortcut that both opens and closes the modal
  • /: Character shortcut that only opens the modal (prevents interference with search typing)
  • Escape: Always works to close the modal regardless of Configuration

resultsFooterComponent​

type: ({ state }, { html }) => JSX.Element | string | Function | optional

The component to display below the search results. Supports template patterns:

  • HTML strings with html helper (recommended for JS CDN): ({ state }, { html }) => html...
  • JSX templates (for React/Preact): ({ state }) => <div>...</div>
  • Function-based templates: (props) => string | JSX.Element | Function

You get access to the current state which allows you to retrieve the number of hits returned, the query etc.

docsearch({
  // ...
  resultsFooterComponent({ state }, { html }) {
    // Using HTML strings with html helper
    return html`
      <div class="DocSearch-HitsFooter">
        <a href="https://docsearch.algolia.com/apply" target="_blank">
          See all ${state.context.nbHits} results
        </a>
      </div>
    `;
  },
});

maxResultsPerGroup​

type: number | optional

The maximum number of results to display per search group. Default is 5.

You can find a working example without JSX in this sandbox

docsearch({
  // ...
  maxResultsPerGroup: 7,
});

recentSearchesLimit​

type: number | default: 7 | optional

The maximum number of recent searches that are stored for the user. Default is 7.

docsearch({
  // ...
  recentSearchesLimit: 12,
  // ...
});

recentSearchesWithFavoritesLimit​

type: number | default: 4 | optional

The maximum number of recent searches that are stored when the user has favorited searches. Default is 4.

docsearch({
  // ...
  recentSearchesWithFavoritesLimit: 5,
  // ...
});

portalContainer (React-only)​

type: Element | DocumentFragment | default: document.body | optional

The element where the DocSearch modal will be portaled. Use this when you need the overlay to render in a custom DOM node—for example when working inside a shadow root, a specific layout container, or a modal manager. When omitted, the modal portals to document.body.

warning

This prop only exists in @docsearch/react. If you are using @docsearch/js, use the container option instead—the value you pass there is both the mount point of the search button and the portal target for the modal.

// assume you have a dedicated modal root in your html
<div id="modal-root" />;

const portalEl = document.getElementById('modal-root');

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="YOUR_INDEX_NAME"
  // render the modal inside #modal-root instead of document.body
  portalContainer={portalEl}
/>;