Federated two-column autocomplete

This example builds on the autocomplete widget guide. It creates a federated autocomplete experience with recent searches and Query Suggestions on the left, and product previews on the right.

This widget is and is subject to change in minor versions.

Desktop
Mobile

Federated autocomplete with recent searches and Query Suggestions on the left and product previews on the right (desktop)

Open CodeSandbox

Run and edit the federated autocomplete example in CodeSandbox.

Explore source code

Browse the source code for the federated autocomplete example on GitHub.

The example has three states. Each one arranges the same two columns differently:

Search state	Left column	Right column
Empty query	Recent searches and popular searches	Quick access
Results	Suggestions and a category	Product (and article) previews
No results	A “no results” message	Popular categories. To show popular categories, add a source that returns category facet values

The sections below build each piece, then combine them in a single panel template. The panel template arranges the sources into two columns, and each source brings its own header and item templates:

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import instantsearch from "instantsearch.js";
import { EXPERIMENTAL_autocomplete } from "instantsearch.js/es/widgets";

import "instantsearch.css/themes/satellite.css";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

const search = instantsearch({
  indexName: "instant_search",
  searchClient,
});

search.addWidgets([
  EXPERIMENTAL_autocomplete({
    container: "#autocomplete",
    placeholder: "Search for products",
    // Left column, top: recent searches from local storage
    showRecent: {
      templates: {
        header: (_, { html }) =>
          html`<span class="ais-AutocompleteIndexHeaderTitle"
            >Recent searches</span
          >`,
      },
    },
    // Left column, bottom: popular Query Suggestions
    showQuerySuggestions: {
      indexName: "instant_search_demo_query_suggestions",
      searchParameters: { hitsPerPage: 5 },
      templates: {
        header: (_, { html }) =>
          html`<span class="ais-AutocompleteIndexHeaderTitle">Suggestions</span>`,
      },
    },
    // Right column: product previews with image, name, price, and highlight
    indices: [
      {
        indexName: "instant_search",
        searchParameters: { hitsPerPage: 5 },
        templates: {
          header: ({ items }, { html }) =>
            items.length === 0
              ? null
              : html`<span class="ais-AutocompleteIndexHeaderTitle"
                  >Products</span
                >`,
          noResults: (_, { html }) =>
            html`<div class="demo-empty">No products found.</div>`,
          item: ({ item }, { html, components }) =>
            html`<div class="demo-product">
              <div class="demo-product-image">
                <img src="${item.image}" alt="${item.name}" />
              </div>
              <div>
                <p class="demo-product-name">
                  ${components.Highlight({ hit: item, attribute: "name" })}
                </p>
                <p class="demo-product-meta">${item.brand} · $${item.price}</p>
              </div>
            </div>`,
        },
      },
    ],
    // Access built-in sources by their element names and index sources by index name.
    templates: {
      panel: ({ elements }, { html }) =>
        html`<div class="demo-grid">
          <div class="demo-column">
            ${elements.recent} ${elements.suggestions}
          </div>
          <div class="demo-column">${elements["instant_search"]}</div>
        </div>`,
    },
  }),
]);

search.start();

Add CSS for the columns, product rows, and state-specific elements. The example style sheet includes classes for:

Two-column grids
Product rows
Quick-access cards
“See all” and no-results states

Add a quick-access panel

You can show promotional cards or shortcuts when the query is empty. Define them as static data and render them in the panel template. When users type a query, show product previews instead:

JavaScript

// Quick-access cards shown in the empty state.
const QUICK_ACCESS = [
  {
    title: "Spring sale",
    subtitle: "up to 60% off",
    image: "https://picsum.photos/seed/spring-sale/300/200",
    href: "#",
  },
  {
    title: "New collection",
    subtitle: "spring / summer",
    image: "https://picsum.photos/seed/new-collection/300/200",
    href: "#",
  },
];

templates: {
  panel: ({ elements, indices }, { html }) => {
    const products = indices.find(
      (index) => index.indexName === "instant_search",
    );
    const isEmptyQuery = products?.results?.query === "";

    return html`<div class="demo-grid">
      <div class="demo-column">${elements.recent} ${elements.suggestions}</div>
      <div class="demo-column">
        ${isEmptyQuery && QUICK_ACCESS.length > 0
          ? html`<ul class="demo-quick">
              ${QUICK_ACCESS.map(
                (entry) => html`<li>
                  <a class="demo-quick-item" href="${entry.href}">
                    <img src="${entry.image}" alt="" />
                    <span class="demo-quick-title">${entry.title}</span>
                    <span class="demo-quick-subtitle">${entry.subtitle}</span>
                  </a>
                </li>`,
              )}
            </ul>`
          : elements["instant_search"]}
      </div>
    </div>`;
  },
},

For dynamic cards, return custom data from an Algolia rule. In the panel template, read the data from results.userData for the products index instead of using a static array.

Add a category suggestion

To show a category suggestion in the left column, find the products index and read the top product’s categories from results.hits[0] in the panel template. Guard against a missing or empty categories attribute, then render the category after the suggestions:

JavaScript

const products = indices.find(
  (index) => index.indexName === "instant_search",
);
// Derive a category from the top product, if any.
const categories = products?.results?.hits?.[0]?.categories ?? [];

// In the left column, after the suggestions:
html`${elements.suggestions}
${categories.length > 0
  ? html`<div class="demo-category">${categories.join(" › ")}</div>`
  : null}`;

Show a “See all” link

The index source has no footer template. To show a See all link with the total number of matching results, read the products index’s results.nbHits in the panel template and render the link after the product previews:

JavaScript

const products = indices.find(
  (index) => index.indexName === "instant_search",
);
const nbHits = products?.results?.nbHits ?? 0;

// In the right column, after the product elements:
html`${elements["instant_search"]}
${nbHits > 5
  ? html`<a class="demo-see-all" href="#">
      See all ${nbHits.toLocaleString()} results
    </a>`
  : null}`;

Show the no-results state

When a result source has no items, the widget doesn’t render its item template. Use the source’s noResults template to show a message such as “No products found”, as shown in the main example.

Combine the empty and typing states

The final panel template combines two states:

For an empty query, show recent and popular searches in the left column and quick-access cards in the right column.
After users enter a query, show Query Suggestions and a category in the left column and product previews in the right column.

To switch between the states:

Remove the header template from showQuerySuggestions.
Render the suggestions heading in the panel template. Use “Popular searches” for an empty query and “Suggestions” for a non-empty query.
Show the heading only when the Query Suggestions source has results.

For the assembled panel template, see src/app.js.

Search and Discovery platform

Optimization and Personalization

AI-powered experiences

Production and scale

Federated two-column autocomplete

Open CodeSandbox

Explore source code

Add a quick-access panel

Add a category suggestion

Show a “See all” link

Show the no-results state

Combine the empty and typing states

See also

Open CodeSandbox

Explore source code

​Add a quick-access panel

​Add a category suggestion

​Show a “See all” link

​Show the no-results state

​Combine the empty and typing states

​See also

Add a quick-access panel

Add a category suggestion

Show a “See all” link

Show the no-results state

Combine the empty and typing states

See also