autocomplete

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

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

The panel’s horizontal position.

Whether to enable the Algolia Insights plugin.

This option accepts an object to configure the plugin. You can see the available options in the plugin’s documentation.

If you don’t pass an insightsClient, it will be automatically detected from the window object, or downloaded from the jsDelivr CDN.

If you manually enable the Insights plugin, this option won’t have any effect.

A dictionary of translations to support internationalization.

1
2
3
4
5
type Translations = Partial<{
  clearButtonTitle: string; // defaults to 'Clear'
  detachedCancelButtonText: string; // defaults to 'Cancel'
  submitButtonTitle: string; // defaults to 'Submit'
}>

Class names to inject for each created DOM element. This is useful to style your autocomplete with external CSS frameworks.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
type ClassNames = Partial<{
  detachedCancelButton: string;
  detachedFormContainer: string;
  detachedContainer: string;
  detachedOverlay: string;
  detachedSearchButton: string;
  detachedSearchButtonIcon: string;
  detachedSearchButtonPlaceholder: string;
  form: string;
  input: string;
  inputWrapper: string;
  inputWrapperPrefix: string;
  inputWrapperSuffix: string;
  item: string;
  label: string;
  list: string;
  loadingIndicator: string;
  panel: string;
  panelLayout: string;
  clearButton: string;
  root: string;
  source: string;
  sourceFooter: string;
  sourceHeader: string;
  submitButton: string;
}>;

Components to register in the Autocomplete rendering lifecycles. Registered components become available in templates, render, and in renderNoResults.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { MyComponent } from './my-components';

autocomplete({
  // ...
  components: {
    MyComponent,
  },
  render({ sections, components, html, render }, root) {
    render(
      html`<div class="aa-PanelLayout aa-Panel--scollable">${sections}</div>
        ${components.MyComponent()}`,
      root
    );
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { render } from 'preact';
import { MyComponent } from './my-components';

autocomplete({
  // ...
  components: {
    MyComponent,
  },
  render({ sections, components }, root) {
    render(
      <Fragment>
        <div className="aa-PanelLayout aa-Panel--scollable">{sections}</div>
        <components.MyComponent />
      </Fragment>,
      root
    );
  },
});

Four components are registered by default:

• Highlight to highlight matches in Algolia results.
• Snippet to snippet matches in Algolia results.
• ReverseHighlight to reverse highlight matches in Algolia results.
• ReverseSnippet to reverse highlight and snippet matches in Algolia results.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        getItems() {
          return [
            /* ... */
          ];
        },
        templates: {
          item({ item, components }) {
            return components.Highlight({ hit: item, attribute: 'name' });
          },
        },
      },
    ];
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
autocomplete({
  // ...
  getSources({ query }) {
    return [
      {
        getItems() {
          return [
            /* ... */
          ];
        },
        templates: {
          item({ item, components }) {
            return <components.Highlight hit={item} attribute="name" />;
          },
        },
      },
    ];
  },
});

The function that renders the autocomplete panel. This is useful to customize the rendering, for example, using multi-row or multi-column layouts.

This is the default implementation:

1
2
3
4
5
6
autocomplete({
  // ...
  render({ children, render }, root) {
    render(children, root);
  },
});

You can use sections, which holds the components tree of your autocomplete, to customize the wrapping layout.

1
2
3
4
5
6
7
8
9
autocomplete({
  // ...
  render({ sections, render, html }, root) {
    render(
      html`<div class="aa-PanelLayout aa-Panel--scrollable">${sections}</div>`,
      root
    );
  },
});

1
2
3
4
5
6
7
8
9
10
11
import { h } from 'preact';

autocomplete({
  // ...
  render({ sections, render }, root) {
    render(
      <div className="aa-PanelLayout aa-Panel--scrollable">{sections}</div>,
      root
    );
  },
});

If you need to split the content across a more complex layout, you can use elements instead to pick which source to display based on its sourceId.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';
import algoliasearch from 'algoliasearch';

const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  key: 'search',
});
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: 'instant_search_demo_query_suggestions',
});

autocomplete({
  // ...
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
  getSources({ query }) {
    return [
      {
        sourceId: 'products',
        // ...
      },
    ];
  },
  render({ elements, render, html }, root) {
    const { recentSearchesPlugin, querySuggestionsPlugin, products } = elements;

    render(
      html`<div class="aa-PanelLayout aa-Panel--scrollable">
        <div>${recentSearchesPlugin} ${querySuggestionsPlugin}</div>
        <div>${products}</div>
      </div>`,
      root
    );
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import { createQuerySuggestionsPlugin } from '@algolia/autocomplete-plugin-query-suggestions';
import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';
import algoliasearch from 'algoliasearch';
import { h } from 'preact';

const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  key: 'search',
});
const querySuggestionsPlugin = createQuerySuggestionsPlugin({
  searchClient,
  indexName: 'instant_search_demo_query_suggestions',
});

autocomplete({
  // ...
  plugins: [recentSearchesPlugin, querySuggestionsPlugin],
  getSources({ query }) {
    return [
      {
        sourceId: 'products',
        // ...
      },
    ];
  },
  render({ elements, render }, root) {
    const { recentSearchesPlugin, querySuggestionsPlugin, products } = elements;

    render(
      <div className="aa-PanelLayout aa-Panel--scrollable">
        <div>
          {recentSearchesPlugin}
          {querySuggestionsPlugin}
        </div>
        <div>{products}</div>
      </div>,
      root
    );
  },
});

The function that renders a no results section when there are no hits. This is useful to let users know that the query returned no results.

There’s no default implementation. By default, Autocomplete closes the panel when there’s no results. Here’s how you can customize this behavior:

1
2
3
4
5
6
autocomplete({
  // ...
  renderNoResults({ state, render }, root) {
    render(`No results for "${state.query}".`, root);
  },
});

The virtual DOM implementation to plug to Autocomplete. It defaults to Preact.

See renderer.

The detached mode turns the dropdown display into a full screen, modal experience.

See Detached mode for more information.

The function that create virtual nodes.

It uses Preact 10’s createElement by default, but you can provide your own implementation.

The component to use to create fragments.

It uses Preact 10’s Fragment by default, but you can provide your own implementation.

The function to render a tree of VNodes into a DOM container.

It uses Preact 10’s render by default, but you can provide your own implementation.

The sources to get the collections from.

The function called to reshape the sources after they’re resolved.

This is useful to transform sources before rendering them. You can group sources by attribute, remove duplicates, create shared limits between sources, etc.

See Reshaping sources for more information.

1
2
3
4
5
type Reshape = (params: {
  sources: AutocompleteReshapeSource[];
  sourcesBySourceId: Record<string, AutocompleteReshapeSource>;
  state: AutocompleteState;
}) => AutocompleteReshapeSource[];

Whether to enable the Algolia Insights plugin.

This option accepts an object to configure the plugin. You can see the available options in the plugin’s documentation.

If you don’t pass an insightsClient, it will be automatically detected from the window object, or downloaded from the jsDelivr CDN.

If you manually enable the Insights plugin, this option won’t have any effect.

An ID for the autocomplete to create accessible attributes.

The function called when the internal state changes.

The action label or icon to present for the enter key on virtual keyboards.

Whether to update the search input value in the middle of a composition session. This is useful when users need to search using non-latin characters.

The placeholder text to show in the search input when there’s no query.

Whether to focus the search input or not when the page is loaded.

The default item index to pre-select.

You should use 0 when the autocomplete is used to open links, instead of triggering a search in an application.

Whether to open the panel on focus when there’s no query.

How many milliseconds must elapse before considering the autocomplete experience stalled.

The initial state to apply when autocomplete is created.

The environment in which your application is running.

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

An implementation of Autocomplete’s Navigator API to redirect users when opening a link.

Learn more on the Navigator API documentation.

The function called to determine whether the panel should open or not.

By default, the panel opens when there are items in the state.

The function called when submitting the Autocomplete form.

The function called when resetting the Autocomplete form.

A flag to activate the debug mode.

This is useful while developing because it keeps the panel open even when the blur event occurs. Make sure to turn it off in production.

See Debugging for more information.

The plugins that encapsulate and distribute custom Autocomplete behaviors.

See Plugins for more information.

The Algolia hit whose attribute to retrieve the highlighted parts from.

The attribute to retrieve the highlighted parts from.

You can use the array syntax to reference nested attributes.

The tag name to use for highlighted parts.

The Algolia hit whose attribute to retrieve the snippeted parts from.

The attribute to retrieve the snippeted parts from.

You can use the array syntax to reference nested attributes.

The tag name to use for snippeted parts.

The Algolia hit whose attribute to retrieve the reverse highlighted parts from.

The attribute to retrieve the reverse highlighted parts from.

You can use the array syntax to reference nested attributes.

The tag name to use for reverse highlighted parts.

The Algolia hit whose attribute to retrieve the reverse snippeted parts from.

The attribute to retrieve the reverse snippeted parts from.

You can use the array syntax to reference nested attributes.

The tag name to use for reverse snippeted parts.

Updates the UI state with fresh sources. You must call this function whenever you mutate the state with setters and want to reflect the changes in the UI.

Updates the Autocomplete instance with new options.

Destroys the Autocomplete instance and removes it from the DOM.