cd46aa71aa
* fixing extra link * adding mention * adding redundant problem * fixing link issue * styling fix
121 lines
3.3 KiB
Markdown
121 lines
3.3 KiB
Markdown
---
|
|
layout: two-columns
|
|
title: Dropdown Behavior
|
|
---
|
|
|
|
Our JS library `docsearch.js` is a wrapper of the [autocomplete.js][1] library.
|
|
This library will listen to keystrokes in the search input, query Algolia, and
|
|
display the results in a dropdown. Everything is already configured for you to
|
|
work with DocSearch, but it also exposes configuration options you can use to go
|
|
even further.
|
|
|
|
## `appId`
|
|
|
|
If you're [running the DocSearch crawler on your own][2], you'll need to define
|
|
your application ID using the `appId` key. If you're using the free hosted
|
|
version, you don't need to add anything.
|
|
|
|
```javascript
|
|
docsearch({
|
|
appId: '<YOUR_CUSTOM_APP_ID>',
|
|
[…],
|
|
});
|
|
```
|
|
|
|
## `handleSelected`
|
|
|
|
This method is called when a suggestion is selected. By default, DocSearch will
|
|
redirect the browser to the results page at the related anchor, but you can
|
|
override it to add your own behavior.
|
|
|
|
The method is called with three arguments:
|
|
|
|
- `input`, a reference to the search `input` element. It comes with the
|
|
`.open()`, `.close()`, `.getVal()` and `.setVal()` methods.
|
|
|
|
- `event`, the actual event triggering the selection. This can come from a click
|
|
or a keyboard navigation.
|
|
|
|
- `suggestion`, the object representing the current selection.
|
|
|
|
```javascript
|
|
docsearch({
|
|
[…],
|
|
handleSelected: function(input, event, suggestion) {
|
|
}
|
|
});
|
|
```
|
|
|
|
## `queryHook`
|
|
|
|
This method will be called on every keystroke to transform the typed keywords
|
|
before sending them to Algolia. By default, it does not do anything, but we
|
|
provide this hook for you to add your own logic if needed.
|
|
|
|
```javascript
|
|
docsearch({
|
|
[…],
|
|
queryHook: function(query) {
|
|
// Transform query, and then return the updated version
|
|
}
|
|
});
|
|
```
|
|
|
|
## `transformData`
|
|
|
|
This method will be called on all suggestions before displaying them. It doesn't
|
|
do anything by default, but we provide this hook for you to add your own logic.
|
|
|
|
```javascript
|
|
docsearch({
|
|
[…],
|
|
transformData: function(suggestions) {
|
|
// Transform the list of suggestions, and the return the updated list
|
|
}
|
|
});
|
|
```
|
|
|
|
## `autocompleteOptions`
|
|
|
|
You can pass any option to the underlying `autocomplete.js` instance by using
|
|
the `autocompleteOptions` parameter. You will find the list of all available
|
|
values in [the official documentation][3].
|
|
|
|
You can also listen to `autocomplete` events through the `.autocomplete`
|
|
property of the `docsearch` instance.
|
|
|
|
```javascript
|
|
const search = docsearch({
|
|
[…]
|
|
autocompleteOptions: {
|
|
// See https://github.com/algolia/autocomplete.js#options
|
|
}
|
|
});
|
|
|
|
// See https://github.com/algolia/autocomplete.js#custom-events
|
|
search.autocomplete.on('autocomplete:opened', event => {
|
|
});
|
|
```
|
|
|
|
## `algoliaOptions`
|
|
|
|
You can pass options to the Algolia API by using the `algoliaOptions` key. You
|
|
will find all Algolia API options in their [own documentation][4].
|
|
|
|
For example, you might want to increase the number of results displayed in the
|
|
dropdown. [`hitsPerPage` set the number of shown hits][5].
|
|
|
|
```javascript
|
|
docsearch({
|
|
algoliaOptions: {
|
|
hitsPerPage: 10,
|
|
// See https://www.algolia.com/doc/api-reference/api-parameters/
|
|
},
|
|
});
|
|
```
|
|
|
|
[1]: https://github.com/algolia/autocomplete.js
|
|
[2]: ./run-your-own.html
|
|
[3]: https://github.com/algolia/autocomplete.js#options
|
|
[4]: https://www.algolia.com/doc/api-reference/api-parameters/
|
|
[5]: https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/
|