Controlling behavior with state

The state object determines how Autocomplete behaves.

Guide Implementing multiple search states

Set an initial state

Initialize the Autocomplete state with the initialState prop.

Copy
autocomplete({
  // ...
  initialState: {
    // This uses the `search` query parameter as the initial query
    query: new URL(window.location).searchParams.get('search'),
  },
});

Listen to state changes

The state changes when users interact with Autocomplete (for example, by updating the search box text or selecting an item). Watch for these changes and respond to them by passing the state object to the onStateChange lifecycle hook.

Copy
autocomplete({
  // ...
  onStateChange({ state }) {
    // Custom code reacting to state changes
    console.log('The Autocomplete state has changed:', state);
  },
});

Update the state

Update the state with setters. For example, to let users fill the search box with a selected Query Suggestion, use setQuery.

When using state setters, call refresh to update the UI with fresh sources based on the updated state.

Copy

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
import { autocomplete } from '@algolia/autocomplete-js';

autocomplete({
  // ...
  getSources({ setQuery, refresh }) {
    return [
      {
        // ...
        templates: {
          item({ item, html }) {
            return html`<div class="aa-ItemContent">
              <div class="aa-ItemSourceIcon">Icon</div>
              <div class="aa-ItemTitle">${item.query}</div>
              <button
                class="aa-ItemActionButton"
                onClick="${(event) => {
                  event.stopPropagation();

                  setQuery(item.query);
                  refresh();
                }}"
              >
                Fill query
              </button>
            </div>`;
          },
        },
      },
    ];
  },
});

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
/** @jsx h */
import { h } from 'preact';
import { autocomplete } from '@algolia/autocomplete-js';

autocomplete({
  // ...
  getSources({ setQuery, refresh }) {
    return [
      {
        // ...
        templates: {
          item({ item }) {
            return (
              <div className="aa-ItemContent">
                <div className="aa-ItemSourceIcon">Icon</div>
                <div className="aa-ItemTitle">{item.query}</div>
                <button
                  className="aa-ItemActionButton"
                  onClick={(event) => {
                    event.stopPropagation();

                    setQuery(item.query);
                    refresh();
                  }}
                >
                  Fill query
                </button>
              </div>
            );
          },
        },
      },
    ];
  },
});

Reference

The state object changes as users interact with Autocomplete but you can also change the state with setters.

State object

The state object is available in all lifecycle hooks.

`activeItemId`	type: number \| null default: null The active (highlighted) item.
`query`	type: string default: "" The search input value. As the `query` changes, the items retrieved from sources also change.
`completion`	type: string \| null default: null The completed version of the query.
`isOpen`	type: boolean default: false Whether the Autocomplete display panel is open or not.
`collections`	type: AutocompleteCollection[] default: [] The Autocomplete collection of items.
`status`	type: "idle" \| "loading" \| "stalled" \| "error" default: "idle" The Autocomplete status.
`context`	type: AutocompleteContext default: {} The global context passed to lifecycle hooks. For more information, see Context.

Setters

`setActiveItemId`	type: (value: number \| null) => void Sets the active (highlighted) item. `null` clears the selection.
`setQuery`	type: (value: string) => void Sets the query.
`setIsOpen`	type: (value: boolean) => void Sets whether the Autocomplete display panel is open or not.
`setStatus`	type: (value: "idle" \| "loading" \| "stalled" \| "error") => void Sets Autocomplete status.
`setCollections`	type: (value: Collection[]) => void Sets the Autcomplete collection of items.
`setContext`	type: (value: AutocompleteContext) => void Sets the context passed to lifecycle hooks. For more information, see Context.

Displaying items with templates

Accessing data with context

Did you find this page helpful?