438 lines
11 KiB
Text
438 lines
11 KiB
Text
---
|
||
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.
|
||
|
||
:::
|
||
|
||
<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.
|
||
|
||
## `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.
|
||
|
||
```js
|
||
docsearch({
|
||
// ...
|
||
transformItems(items) {
|
||
return items.map((item) => ({
|
||
...item,
|
||
content: item.content.toUpperCase(),
|
||
}));
|
||
},
|
||
});
|
||
```
|
||
|
||
## `hitComponent`
|
||
|
||
> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional**
|
||
|
||
The component to display each item.
|
||
|
||
See the [default implementation][8].
|
||
|
||
## `transformSearchClient`
|
||
|
||
> `type: function` | `default: searchClient => searchClient` | **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',
|
||
},
|
||
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: 'to select',
|
||
selectKeyAriaLabel: 'Enter key',
|
||
navigateText: 'to navigate',
|
||
navigateUpKeyAriaLabel: 'Arrow up',
|
||
navigateDownKeyAriaLabel: 'Arrow down',
|
||
closeText: 'to close',
|
||
closeKeyAriaLabel: 'Escape key',
|
||
searchByText: 'Search 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.
|
||
|
||
```js
|
||
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](#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).
|
||
|
||
```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">
|
||
|
||
## `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.
|
||
|
||
```jsx
|
||
<DocSearch
|
||
// ...
|
||
transformItems={(items) => {
|
||
return items.map((item) => ({
|
||
...item,
|
||
content: item.content.toUpperCase(),
|
||
}));
|
||
}}
|
||
/>
|
||
```
|
||
|
||
## `hitComponent`
|
||
|
||
> `type: ({ hit, children }) => JSX.Element` | `default: Hit` | **optional**
|
||
|
||
The component to display each item.
|
||
|
||
See the [default implementation][8].
|
||
|
||
## `transformSearchClient`
|
||
|
||
> `type: function` | `default: searchClient => searchClient` | **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',
|
||
},
|
||
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: 'to select',
|
||
selectKeyAriaLabel: 'Enter key',
|
||
navigateText: 'to navigate',
|
||
navigateUpKeyAriaLabel: 'Arrow up',
|
||
navigateDownKeyAriaLabel: 'Arrow down',
|
||
closeText: 'to close',
|
||
closeKeyAriaLabel: 'Escape key',
|
||
searchByText: 'Search 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.
|
||
|
||
```jsx
|
||
<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](#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 in this sandbox](https://codesandbox.io/s/docsearch-v3-resultsfootercomponent-wzie9y).
|
||
|
||
```jsx
|
||
<DocSearch
|
||
// ...
|
||
resultsFooterComponent={({ state }) => {
|
||
return <h1>{state.context.nbHits} hits found</h1>;
|
||
}}
|
||
/>
|
||
```
|
||
|
||
</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/
|