autocomplete-theme-classic

The classic theme provides styling for Autocomplete experiences.

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.

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

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.9/dist/theme.min.css"
  integrity="sha256-6VZg2e7ColRlFrMMzaMK5UHpeEPD2o4pJ4kBBPvt19E="
  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.

JavaScript

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.

JavaScript

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

Header

Here’s the markup for a header template.

JavaScript

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" />