Adding recent searches

Most autocomplete menus include suggested searches. You can make the experience more user-friendly by adding recent searches a user has made. This UX lets users easily recall their past searches in case they want to search for them again.

Before you begin

This guide assumes that you know HTML, CSS, and JavaScript and that you have existing HTML with an input element where you want to implement an autocomplete drop-down menu.

Using this plugin doesn’t require an Algolia application. If you plan on including other sections in your autocomplete such as suggested searches, you do need an Algolia application with the Query Suggestions feature enabled.

Getting started

Begin with the following Autocomplete starter code. Create a file called index.js in your src directory:

1
2
3
4
5
6
7
import { autocomplete } from '@algolia/autocomplete-js';

autocomplete({
  container: '#autocomplete',
  plugins: [],
  openOnFocus: true,
});

This starter code assumes you want to insert the autocomplete into a DOM element with autocomplete as an id. Change the container to match your markup. Setting openOnFocus to true ensures that the drop-down menu appears as soon as a user focuses the input.

For now, plugins is an empty array, but you’ll learn how to add the Recent Searches plugin next.

Adding recent searches

The Autocomplete library provides the createLocalStorageRecentSearchesPlugin function for creating a recent searches plugin out-of-the-box. To use it, you need to provide a key and limit.

The key can be any string and is required to differentiate search histories if you have multiple Autocomplete UI elements on one page. The limit defines the maximum number of recent searches to display.

1
2
3
4
5
6
7
8
9
10
11
12
13
import { autocomplete } from '@algolia/autocomplete-js';
import { createLocalStorageRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';

const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  key: 'RECENT_SEARCH',
  limit: 5,
});

autocomplete({
  container: '#autocomplete',
  plugins: [recentSearchesPlugin],
  openOnFocus: true,
});

Since the recentSearchesPlugin reads from localStorage, you won’t see any recent searches in your implementation until you’ve made some searches. To submit a search, be sure to press Enter on the query. Once you do, you’ll see it appear as a recent search. Try it out here:

Customizing recent searches

The createLocalStorageRecentSearchesPlugin creates a functional plugin out of the box. You may want to customize some aspects of it, depending on your use case. To change templates or other source configuration options, you can use transformSource. The function includes the original source, which you should return along with any options you want to add or overwrite.

For example, if you use Autocomplete as an entry point to a search results page, you can turn recent searches into links by modifying getItemUrl and the item template.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  // ...
  transformSource({ source }) {
    return {
      ...source,
      getItemUrl({ item }) {
        return `/search?q=${item.query}`;
      },
      templates: {
        item(params) {
          const { item, html } = params;

          return html`<a class="aa-ItemLink" href="/search?q=${item.query}">
            ${source.templates.item(params).props.children}
          </a>`;
        },
      },
    };
  },
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  // ...
  transformSource({ source }) {
    return {
      ...source,
      getItemUrl({ item }) {
        return `/search?q=${item.query}`;
      },
      templates: {
        item(params) {
          const { item } = params;

          return (
            <a className="aa-ItemLink" href={`/search?q=${item.query}`}>
              {source.templates.item(params).props.children}
            </a>
          );
        },
      },
    };
  },
});

If you use Autocomplete on the same page as your main search and want to avoid reloading the full page when an item is selected, you can modify your search query state when a user selects an item with onSelect:

1
2
3
4
5
6
7
8
9
10
11
12
const recentSearchesPlugin = createLocalStorageRecentSearchesPlugin({
  // ...
  transformSource({ source }) {
    return {
      ...source,
      onSelect({ item }) {
        // Assuming the refine function updates the search page state.
        refine(item.query);
      },
    };
  },
});

Using your own storage

Sometimes, you may not want to use local storage for your recent search data. You may want to use session storage or handle recent searches on your backend. If so, you can use the createRecentSearchesPlugin to implement your own storage:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { autocomplete } from '@algolia/autocomplete-js';
import { createRecentSearchesPlugin } from '@algolia/autocomplete-plugin-recent-searches';

const recentSearchesPlugin = createRecentSearchesPlugin({
  // Implement your own storage
  storage: {
    getAll() {},
    onAdd() {},
    onRemove() {},
  },
});

autocomplete({
  container: '#autocomplete',
  openOnFocus: true,
  plugins: [recentSearchesPlugin],
});

Next steps

This tutorial focuses on creating and adding recent searches to an autocomplete menu. Most autocomplete menus include recent searches in addition to suggested searches and possibly other items.