docsearch/docs/src/behavior.md

layout	title
two-columns	Dropdown Behavior

Our JS library docsearch.js is a wrapper of the autocomplete.js 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, 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.

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.

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.

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.

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.

You can also listen to autocomplete events through the .autocomplete property of the docsearch instance.

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.

For example, you might want to increase the number of results displayed in the dropdown. hitsPerPage set the number of shown hits.

docsearch({
  algoliaOptions: {
    hitsPerPage: 10,
    // See https://www.algolia.com/doc/api-reference/api-parameters/
  },
});