autocomplete-theme-classic

Prefer using the Autocomplete widget from InstantSearch instead of the standalone Autocomplete library. It integrates more closely with your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

The theme is a neutral and clean starter. You can use it as a base and customize it with CSS variables. If you want to build your own theme, you can start from the Classic theme and adjust it.

Installation

First, you need to install the theme.

npm install @algolia/autocomplete-theme-classic

yarn add @algolia/autocomplete-theme-classic

Then import it in your project:

JavaScript

import "@algolia/autocomplete-theme-classic";

If you don’t use a package manager, you can link the style sheet in your HTML:

HTML

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-theme-classic@1.19.11/dist/theme.min.css"
  integrity="sha256-T75qTJHq8d1iBuH4rJ1yar/kRO7fx479qzH+e6xSgW0="
  crossorigin="anonymous"
/>

CSS variables

The theme uses CSS variables that you can customize in your own CSS.

All colors are defined with two variables: one for the RGB values and one for the alpha layer. This lets you adjust each value independently.

Size and spacing

Name	Type	Description
`--aa-base-unit`	`number`	Base value to calculate font sizes and spacing
`--aa-spacing-factor`	`number`	Base value to calculate spacing increments
`--aa-spacing`	`length`	Fixed spacing value derived from `--aa-base-unit` and `--aa-spacing-factor`
`--aa-spacing-half`	`length`	Half of `--aa-spacing`
`--aa-panel-max-height`	`length`	Maximum height for the panel before showing a vertical scrollbar

Z-index

Name	Type	Description
`--aa-base-z-index`	`integer`	Base value to calculate all z-index.

Font

Name	Type	Description
`--aa-font-size`	`length`	Fixed font size derived from `--aa-base-unit`
`--aa-font-family`	`string`	Base font stack
`--aa-font-weight-medium`	`number`	Medium font weight for `--aa-font-family` (usually 500)
`--aa-font-weight-semibold`	`number`	Semibold font weight for `--aa-font-family` (usually 600)
`--aa-font-weight-bold`	`number`	Bold font weight for `--aa-font-family` (usually 700)

Icons

Name	Type	Description
`--aa-icon-size`	`length`	Fixed icon size value
`--aa-icon-stroke-width`	`number`	Fixed icon stroke width
`--aa-icon-color-rgb`	`integer`,`integer`,`integer`	RGB values for the icon color
`--aa-icon-color-alpha`	`number`	Alpha value for the icon color
`--aa-action-icon-size`	`length`	Fixed action icon size value

Text colors

Name	Type	Description
`--aa-text-color-rgb`	`integer`,`integer`,`integer`	RGB values for the global text color
`--aa-text-color-alpha`	`number`	Alpha value for the global text color
`--aa-primary-color-rgb`	`integer`,`integer`,`integer`	RGB values for the accent color
`--aa-primary-color-alpha`	`number`	Alpha value for the accent color
`--aa-muted-color-rgb`	`integer`,`integer`,`integer`	RGB values for the muted color
`--aa-muted-color-alpha`	`number`	Alpha value for the muted color

Border colors

Name	Type	Description
`--aa-panel-border-color-rgb`	`integer`,`integer`,`integer`	RGB values for the panel border
`--aa-panel-border-color-alpha`	`number`	Alpha value for the panel border
`--aa-input-border-color-rgb`	`integer`,`integer`,`integer`	RGB values for the input border
`--aa-input-border-color-alpha`	`number`	Alpha value for the input border

Background colors

Name	Type	Description
`--aa-background-color-rgb`	`integer`,`integer`,`integer`	RGB values for the background
`--aa-background-color-alpha`	`number`	Alpha value for the background
`--aa-input-background-color-rgb`	`integer`,`integer`,`integer`	RGB values for the input background
`--aa-input-background-color-alpha`	`number`	Alpha value for the input background
`--aa-selected-color-rgb`	`integer`,`integer`,`integer`	RGB values for selected, active, or focused elements
`--aa-selected-color-alpha`	`number`	Alpha value for selected, active, or focused elements
`--aa-description-highlight-background-color-rgb`	`integer`,`integer`,`integer`	RGB values for the description highlight background
`--aa-description-highlight-background-color-alpha`	`number`	Alpha value for the description highlight background

Detached mode

Name	Type	Description
`--aa-detached-media-query`	`media` query	Media query to enable detached mode on smaller devices
`--aa-detached-modal-media-query`	`media` query	Media query to enable detached mode on bigger devices
`--aa-detached-modal-max-width`	`length`	Maximum modal width in detached mode
`--aa-detached-modal-max-height`	`length`	Maximum modal height in detached mode
`--aa-overlay-color-rgb`	`integer`,`integer`,`integer`	RGB values for the overlay
`--aa-overlay-color-alpha`	`number`	Alpha value for the overlay

Shadows

Name	Type	Description
`--aa-panel-shadow`	`box-shadow`	Shadow for the panel

Scrollbar

Name	Type	Description
`--aa-scrollbar-width`	`length`	Scrollbar width
`--aa-scrollbar-track-background-color-rgb`	`integer`,`integer`,`integer`	RGB values for the scrollbar track
`--aa-scrollbar-track-background-color-alpha`	`number`	Alpha value for the scrollbar track
`--aa-scrollbar-thumb-background-color-rgb`	`integer`,`integer`,`integer`	RGB values for the scrollbar thumb
`--aa-scrollbar-thumb-background-color-alpha`	`number`	Alpha value for the scrollbar thumb

To customize a value, you can create a custom style sheet and override the variable.

CSS

:root {
  --aa-icon-size: 24px;
}

Make sure to load these styles after the theme.

Templates

For the theme to work out of the box, you need to use a conventional CSS class set. All class names from the theme come with an aa- namespace to avoid interfering with your own styles.

Item

Here’s the markup for an item template.

autocomplete({
  // ...
  templates: {
    item({ item, components, html }) {
      return html`<div class="aa-ItemWrapper">
        <div class="aa-ItemContent">
          <div class="aa-ItemIcon">
            <img
              src="${item.image}"
              alt="${item.name}"
              width="40"
              height="40"
            />
          </div>
          <div class="aa-ItemContentBody">
            <div class="aa-ItemContentTitle">
              ${components.Highlight({ hit: item, attribute: "name" })}
            </div>
            <div class="aa-ItemContentDescription">
              ${components.Snippet({ hit: item, attribute: "description" })}
            </div>
          </div>
        </div>
        <div class="aa-ItemActions">
          <button
            class="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
            type="button"
            title="Select"
          >
            <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor">
              <path
                d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z"
              />
            </svg>
          </button>
        </div>
      </div>`;
    },
  },
});

autocomplete({
  // ...
  templates: {
    item({ item, components }) {
      return (
        <div className="aa-ItemWrapper">
          <div className="aa-ItemContent">
            <div className="aa-ItemIcon">
              <img src={item.image} alt={item.name} width="40" height="40" />
            </div>
            <div className="aa-ItemContentBody">
              <div className="aa-ItemContentTitle">
                <components.Highlight hit={item} attribute="name" />
              </div>
              <div className="aa-ItemContentDescription">
                <components.Snippet hit={item} attribute="description" />
              </div>
            </div>
          </div>
          <div className="aa-ItemActions">
            <button
              className="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
              type="button"
              title="Select"
            >
              <svg
                viewBox="0 0 24 24"
                width="20"
                height="20"
                fill="currentColor"
              >
                <path d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z" />
              </svg>
            </button>
          </div>
        </div>
      );
    },
  },
});

Link item

To wrap an item within a link, use the .aa-ItemLink class in place of the element with .aa-ItemWrapper. Make sure not to use both together.

autocomplete({
  // ...
  templates: {
    item({ item, html }) {
      return html`<a class="aa-ItemLink" href="${item.url}"> /* ... */ </a>`;
    },
  },
});

autocomplete({
  // ...
  templates: {
    item({ item }) {
      return (
        <a className="aa-ItemLink" href={item.url}>
          {/* ... */}
        </a>
      );
    },
  },
});

Here’s the markup for a header template.

autocomplete({
  // ...
  templates: {
    header({ html }) {
      return html`<span class="aa-SourceHeaderTitle">Products</span>
        <div class="aa-SourceHeaderLine" />`;
    },
    // ...
  },
});

autocomplete({
  // ...
  templates: {
    header() {
      return (
        <Fragment>
          <span className="aa-SourceHeaderTitle">Products</span>
          <div className="aa-SourceHeaderLine" />
        </Fragment>
      );
    },
    // ...
  },
});

No results

Here’s the markup for a noResults template.

JavaScript

autocomplete({
  // ...
  templates: {
    noResults() {
      return "No products for this query.";
    },
    // ...
  },
});

Additional CSS classes

The theme provides a set of optional classes for you to use in different contexts.

Modifiers

.aa-ItemIcon--noBorder removes the border of the icon
.aa-ItemIcon--alignTop aligns the icon to the top (recommended when the template is longer than three lines)
.aa-ItemIcon--picture makes the icon larger (recommended when using an image and the template is longer than three lines)
.aa-Panel--scrollable declares the scrollable containers of the panel

Utilities

.aa-ActiveOnly displays an element only when the item is active
.aa-DesktopOnly displays an element only on desktop devices
.aa-TouchOnly displays an element only on tap devices

Dark mode

The theme supports dark mode. You can enable it on the body tag in two different ways:

<body data-theme="dark" />
<body class="dark" />

​Installation

​CSS variables

​Size and spacing

​Z-index

​Font

​Icons

​Text colors

​Border colors

​Background colors

​Detached mode

​Shadows

​Scrollbar

​Templates

​Item

​Link item

​Header

​No results

​Additional CSS classes

​Modifiers

​Utilities

​Dark mode

Installation

CSS variables

Size and spacing

Z-index

Font

Icons

Text colors

Border colors

Background colors

Detached mode

Shadows

Scrollbar

Templates

Item

Link item

Header

No results

Additional CSS classes

Modifiers

Utilities

Dark mode