docsearch/packages/website/versioned_docs/version-v3/api.mdx

---
title: API Reference
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import useBaseUrl from '@docusaurus/useBaseUrl';

:::info

The following content is for **[DocSearch v3][2]**.
If you are using **[DocSearch v2][3]**, see the **[legacy][4]** documentation.

If you are looking for **DocSearch v4**, see the documentation **[here][12]**.

:::

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

## `container`

> `type: string | HTMLElement` | **required**

The container for the DocSearch search box. You can either pass a [CSS selector][5] or an [Element][6]. 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.

</TabItem>
</Tabs>

## `appId`

> `type: string` | **required**

Your Algolia application ID.

## `apiKey`

> `type: string` | **required**

Your Algolia Search API key.

## `indexName`

> `type: string` | **required**

Your Algolia index name.

## `placeholder`

> `type: string` | `default: "Search docs"` | **optional**

The placeholder of the input of the DocSearch pop-up modal.

## `searchParameters`

> `type: SearchParameters` | **optional**

The [Algolia Search Parameters][7].

## `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.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

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

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  // ...
  transformItems={(items) => {
    return items.map((item) => ({
      ...item,
      content: item.content.toUpperCase(),
    }));
  }}
/>
```

</TabItem>
</Tabs>

## `hitComponent`

> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional**

The component to display each item.

See the [default implementation][8].

## `transformSearchClient`

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

Useful for transforming the [Algolia Search Client][10], for example to [debounce search queries][9]

## `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.

## `navigator`

> `type: Navigator` | **optional**

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

Learn more on the [Navigator API][11] 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.

<details>
<summary>docSearchTranslations</summary>
<div>

```ts
const translations: DocSearchTranslations = {
  button: {
    buttonText: 'Search',
    buttonAriaLabel: 'Search',
  },
  modal: {
    searchBox: {
      resetButtonTitle: 'Clear the query',
      resetButtonAriaLabel: 'Clear the query',
      cancelButtonText: 'Cancel',
      cancelButtonAriaLabel: 'Cancel',
      searchInputLabel: 'Search',
    },
    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',
    },
    errorScreen: {
      titleText: 'Unable to fetch results',
      helpText: 'You might want to check your network connection.',
    },
    footer: {
      selectText: 'Select',
      selectKeyAriaLabel: 'Enter key',
      navigateText: 'Navigate',
      navigateUpKeyAriaLabel: 'Arrow up',
      navigateDownKeyAriaLabel: 'Arrow down',
      closeText: 'Close',
      closeKeyAriaLabel: 'Escape key',
      poweredByText: 'Powered by',
    },
    noResultsScreen: {
      noResultsText: 'No results for',
      suggestedQueryText: 'Try searching for',
      reportMissingResultsText: 'Believe this query should return results?',
      reportMissingResultsLinkText: 'Let us know.',
    },
  },
};
```

</div>
</details>

## `getMissingResultsUrl`

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

Function to return the URL of your documentation repository.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

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

</TabItem>

<TabItem value="react">

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

</TabItem>
</Tabs>

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](#translations) property.

<div className="uil-ta-center">
  <img src={useBaseUrl('img/assets/noResultsScreen.png')} alt="No results screen with informative message" />
</div>

## `resultsFooterComponent`

> `type: ({ state }) => JSX.Element` | **optional**

The component to display below the search results.

You get access to the [current state](https://github.com/algolia/autocomplete/blob/next/packages/autocomplete-core/src/types/AutocompleteState.ts) which allows you to retrieve the number of hits returned, the query etc.

[You can find a working example without JSX in this sandbox](https://codesandbox.io/s/docsearch-v3-resultsfootercomponent-without-jsx-jperd5).

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  // ...
  resultsFooterComponent({ state }) {
    return {
      // The HTML `tag`
      type: 'a',
      ref: undefined,
      constructor: undefined,
      key: state.query,
      // Its props
      props: {
        href: 'https://docsearch.algolia.com/apply',
        target: '_blank',
        onClick: (event) => {
          console.log(event);
        },
        // Raw text rendered in the HTML element
        children: `${state.context.nbHits} hits found!`,
      },
      __v: null,
    };
  },
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  // ...
  resultsFooterComponent={({ state }) => {
    return <h1>{state.context.nbHits} hits found</h1>;
  }}
/>
```

</TabItem>
</Tabs>

## `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](https://codesandbox.io/s/docsearch-v3-maxresultspergroup-without-jsx-ct9m22?file=/src/index.js)

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', }
  ]
}>
<TabItem value="js">

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

</TabItem>

</Tabs>

## `theme`

> `type: DocSearchTheme` | `default: "light"` | **optional**

Theme for DocSearch. Can be either `light` or `dark`.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  // ...
  theme: 'light',
});
```
</TabItem>
</Tabs>

[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
[2]: https://github.com/algolia/docsearch/
[3]: https://github.com/algolia/docsearch/tree/master
[4]: /docs/legacy/dropdown
[5]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[6]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[7]: https://www.algolia.com/doc/api-reference/search-api-parameters/
[8]: https://github.com/algolia/docsearch/blob/main/packages/docsearch-react/src/Hit.tsx
[9]: https://codesandbox.io/s/docsearch-v3-debounced-search-gnx87
[10]: https://www.algolia.com/doc/api-client/getting-started/what-is-the-api-client/javascript/?client=javascript
[11]: https://www.algolia.com/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation/
[12]: /docs/docsearch