createTagsPlugin

Autocomplete is also available as an experimental widget in InstantSearch, making it easier to integrate into your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

This plugin lets you manage and display tags in Autocomplete. You can use tags in various ways, such as displaying filters or representing navigation steps.

Install the plugin

npm install @algolia/autocomplete-plugin-tags

yarn add @algolia/autocomplete-plugin-tags

Import the plugin into your project

JavaScript

import { autocomplete } from "@algolia/autocomplete-js";
import { createTagsPlugin } from "@algolia/autocomplete-plugin-tags";

const tagsPlugin = createTagsPlugin();

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

The plugin includes CSS compatible with autocomplete-theme-classic.

JavaScript

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

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

HTML

<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-tags@1.19.9/dist/umd/index.production.js"
  integrity="sha256-m15NuZIZ6jTQq1uNRug0NYOuElnppLH+/9ZLJNvRQ4o="
  crossorigin="anonymous"
></script>
<script>
  const { createTagsPlugin } = window["@algolia/autocomplete-plugin-tags"];
</script>

To load the tags plugin’s theme:

HTML

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-plugin-tags@1.19.9/dist/umd/index.production.js"
  integrity="sha256-m15NuZIZ6jTQq1uNRug0NYOuElnppLH+/9ZLJNvRQ4o="
  crossorigin="anonymous"
/>

Initialize the plugin with `initialTags`

The plugin lets you pass initialTags for Autocomplete. Use it when deriving tags from an existing state, such as the route or filter status. For example, if the URL reflects the current filter state, you can initialize the plugin with them when the page loads before the Autocomplete instance starts.

JavaScript

// 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 });

Modify tags

By default, the plugin populates a source with the current tags. Users can navigate through them as with any other source and delete them on click or selection. You can customize the source with transformSource. If you want to display tags manually, for example, with the render function or in the search box, you can prevent the plugin from returning a source. The plugin exposes an API on the Context to let you access tags.

// ...
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,
    );
  },
});

// ...
const tagsPlugin = createTagsPlugin({
  // ...
  transformSource({ source }) {
    return undefined;
  },
});

autocomplete({
  // ...
  render({ sections, state }, root) {
    render(
      <div classbody="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 for removing individual tags.

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

// ...

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,
    );
  },
});

// ...

autocomplete({
  // ...
  render({ sections, state }, root) {
    render(
      <div classbody="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 when interacting with tags outside the Autocomplete instance.

JavaScript

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

Parameters

initialTags

BaseTag<TTag>[]

A set of initial tags to pass to the plugin.You can use this to pass initial refinements (for example, from local state) without triggering the Autocomplete lifecycle.

TypeScript

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

getTagsSubscribers

(): Array<{ sourceId: string, getTag(params: { item: TItem }): BaseTag<TTag> }>

A function to specify what sources the plugin should subscribe to. The plugin adds a tag when selecting an item from these sources.

sourceId: the sourceId of the source to subscribe to.
getTag: a function to return a tag from the selected items.

JavaScript

const tagsPlugin = createTagsPlugin({
  getTagsSubscribers() {
    return [
      {
        sourceId: "brands",
        getTag({ item }) {
          return {
            ...item,
            label: item.name,
          };
        },
      },
    ];
  },
});

transformSource

function

Type definition

(params: {
  source: AutocompleteSource<Tag<TTag>>,
  state: AutocompleteState<Tag<TTag>>,
}): AutocompleteSource<Tag<TTag>> | undefined

A function to transform the returned tags source.

Example

const tagsPlugin = createTagsPlugin({
  transformSource({ source }) {
    return {
      ...source,
      templates: {
        ...source.templates,
        item({ item }) {
          return `${item.label} in ${item.type}`;
        },
      },
    };
  },
});

onChange

(params: OnChangeParams<TTag>): void

TypeScript

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

The function called when the list of tags changes. This is useful to customize the behavior of Autocomplete when such an event occurs, or integrate with third-party code.

createTagsPlugin

Install the plugin

Import the plugin into your project

Initialize the plugin with `initialTags`

Modify tags

Parameters

Returns

`data`

​Install the plugin

​Import the plugin into your project

​Initialize the plugin with initialTags

​Modify tags

​Parameters

​Returns

​data

Install the plugin

Import the plugin into your project

Initialize the plugin with `initialTags`

Modify tags

Parameters

Returns

`data`