createTagsPlugin

The Autocomplete Tags plugin lets you manage and display tags in the autocomplete.

You can use tags for a wide variety of use cases: filtering, displaying refinements, representing navigation steps, and more.

Installation

First, you need to install the plugin.

1
2
3
yarn add @algolia/autocomplete-plugin-tags
# or
npm install @algolia/autocomplete-plugin-tags

Then import it in your project:

1
import { createTagsPlugin } from '@algolia/autocomplete-plugin-tags';

The plugin provides a theme compatible with the autocomplete-theme-classic package.

1
import '@algolia/autocomplete-plugin-tags/dist/theme.min.css';

If you don’t use a package manager, you can use the HTML script element:

1
2
3
4
5
6
7
8
9
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-tags/dist/theme.min.css"
/>

<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-tags"></script>
<script>
  const { createTagsPlugin } = window['@algolia/autocomplete-plugin-tags'];
</script>

Examples

1
2
3
4
5
6
7
8
9
10
import { autocomplete } from '@algolia/autocomplete-js';
import { createTagsPlugin } from '@algolia/autocomplete-plugin-tags';

const tagsPlugin = createTagsPlugin();

autocomplete({
  // ...
  container: '#autocomplete',
  plugins: [tagsPlugin],
});

The plugin lets you pass initialTags to start Autocomplete with initial tags. You can use this when you’re deriving tags from existing state, such as the route, or existing refinements.

For example, if the URL reflects the current refinements, you can initialize the plugin with them when the page loads, before the Autocomplete instance starts.

1
2
3
4
5
6
// Current URL: https://example.org/?category=Phones&brand=Apple

const parameters = Array.from(new URLSearchParams(location.search));
const initialTags = parameters.map(([facet, label]) => ({ label, facet })); // [{ label: 'Phones', facet: 'category' }, { label: 'Apple', facet: 'brand' }]

const tagsPlugin = createTagsPlugin({ initialTags });

By default, the plugin populates a source with the current tags. You can navigate through them like with any other source, and delete them on click or on select. You can customize the source using transformSource.

If you prefer displaying your tags by hand, for example in the render function of Autocomplete or in the search box, near the query, you can prevent the plugin from returning a source and display tags yourself. The plugin exposes an API on the Context to let you access tags.

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
// ...
const tagsPlugin = createTagsPlugin({
  // ...
  transformSource({ source }) {
    return undefined;
  },
});

autocomplete({
  // ...
  render({ sections, html, render }, root) {
    render(
      html`<div class="aa-PanelLayout aa-Panel--scrollable">
        <ul>
          ${state.context.tagsPlugin.tags.map(
            (tag) =>
              html`<li key="${tag.label}" onClick="${() => tag.remove()}">
                ${tag.label}
              </li>`
          )}
        </ul>
        <div>${sections}</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
// ...
const tagsPlugin = createTagsPlugin({
  // ...
  transformSource({ source }) {
    return undefined;
  },
});

autocomplete({
  // ...
  render({ sections, state }, root) {
    render(
      <div className="aa-PanelLayout aa-Panel--scrollable">
        <ul>
          {state.context.tagsPlugin.tags.map((tag) => (
            <li key={tag.label} onClick={() => tag.remove()}>
              {tag.label}
            </li>
          ))}
        </ul>
        <div>{sections}</div>
      </div>,
      root
    );
  },
});

Returned tags expose a remove function to conveniently remove individual tags.

The plugin also exposes an addTags and a setTags function on the Context to update the list of tags.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// ...

autocomplete({
  // ...
  render({ sections, state, html, render }, root) {
    render(
      html`<div class="aa-PanelLayout aa-Panel--scrollable">
        <button onClick="${() => state.context.tagsPlugin.setTags([])}">
          Clear all tags
        </button>
        /* ... */
      </div>`,
      root
    );
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// ...

autocomplete({
  // ...
  render({ sections, state }, root) {
    render(
      <div className="aa-PanelLayout aa-Panel--scrollable">
        <button onClick={() => state.context.tagsPlugin.setTags([])}>
          Clear all tags
        </button>
        {/* ... */}
      </div>,
      root
    );
  },
});

You can access the same API to retrieve and modify tags directly on the plugin. This is helpful to interact with tags outside of the Autocomplete instance.

1
2
3
document.getElementById('#clear-speakers').addEventListener('click', () => {
  tagsPlugin.data.setTags([]);
});

Parameters

1
type BaseTag<TTag = Record<string, unknown>> = TTag & { label: string };

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const tagsPlugin = createTagsPlugin({
  getTagsSubscribers() {
    return [
      {
        sourceId: 'brands',
        getTag({ item }) {
          return {
            ...item,
            label: item.name,
          };
        },
      },
    ];
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
const tagsPlugin = createTagsPlugin({
  transformSource({ source }) {
    return {
      ...source,
      templates: {
        ...source.templates,
        item({ item }) {
          return `${item.label} in ${item.type}`;
        },
      },
    };
  },
});

1
2
3
4
5
const tagsPlugin = createTagsPlugin({
  transformSource() {
    return undefined;
  },
});

1
2
3
4
type OnChangeParams<TTag> = PluginSubscribeParams<any> & {
  prevTags: Array<Tag<TTag>>;
  tags: Array<Tag<TTag>>;
};

Returns

data

1
type Tag<TTag> = BaseTag<TTag> & { remove(): void };

1
tagsPlugin.data.addTags([{ label: 'Apple', facet: 'brand' }]);

1
tagsPlugin.data.setTags([{ label: 'Apple', facet: 'brand' }]);

1
2
3
4
// Filters out all tags with `facet` "brand"
const newTags = tagsPlugin.data.tags.filter((tag) => tag.facet !== 'brand');

tagsPlugin.data.setTags(newTags);