> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# autocomplete-theme-classic

> The classic theme provides styling for Autocomplete experiences.

<Tip>
  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](/doc/api-reference/widgets/autocomplete/js) or
  [React InstantSearch](/doc/api-reference/widgets/autocomplete/react).
</Tip>

The theme is a neutral and clean starter.
You can use it as a base and customize it with [CSS variables](#css-variables).

If you want to build your own theme,
you can [start from the Classic theme](https://github.com/algolia/autocomplete/tree/next/packages/autocomplete-theme-classic) and adjust it.

## Installation

First, you need to install the theme.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/autocomplete-theme-classic
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/autocomplete-theme-classic
  ```
</CodeGroup>

Then import it in your project:

```js JavaScript icon=code theme={"system"}
import "@algolia/autocomplete-theme-classic";
```

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

```html HTML icon=code-xml theme={"system"}
<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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) that you can customize in your own CSS.

<Info>
  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.
</Info>

### Size and spacing

| Name                    | Type                                                                | Description                                                                 |
| ----------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `--aa-base-unit`        | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number) | Base value to calculate font sizes and spacing                              |
| `--aa-spacing-factor`   | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number) | Base value to calculate spacing increments                                  |
| `--aa-spacing`          | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | Fixed spacing value derived from `--aa-base-unit` and `--aa-spacing-factor` |
| `--aa-spacing-half`     | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | Half of `--aa-spacing`                                                      |
| `--aa-panel-max-height` | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/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`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | Fixed font size derived from `--aa-base-unit`             |
| `--aa-font-family`          | [`string`](https://developer.mozilla.org/en-US/docs/Web/CSS/string) | Base font stack                                           |
| `--aa-font-weight-medium`   | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number) | Medium font weight for `--aa-font-family` (usually 500)   |
| `--aa-font-weight-semibold` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number) | Semibold font weight for `--aa-font-family` (usually 600) |
| `--aa-font-weight-bold`     | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number) | Bold font weight for `--aa-font-family` (usually 700)     |

### Icons

| Name                     | Type                                                                                      | Description                    |
| ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------ |
| `--aa-icon-size`         | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                       | Fixed icon size value          |
| `--aa-icon-stroke-width` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Fixed icon stroke width        |
| `--aa-icon-color-rgb`    | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the icon color  |
| `--aa-icon-color-alpha`  | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the icon color |
| `--aa-action-icon-size`  | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                       | Fixed action icon size value   |

### Text colors

| Name                       | Type                                                                                      | Description                           |
| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------- |
| `--aa-text-color-rgb`      | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the global text color  |
| `--aa-text-color-alpha`    | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the global text color |
| `--aa-primary-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the accent color       |
| `--aa-primary-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the accent color      |
| `--aa-muted-color-rgb`     | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the muted color        |
| `--aa-muted-color-alpha`   | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the muted color       |

### Border colors

| Name                            | Type                                                                                      | Description                      |
| ------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------- |
| `--aa-panel-border-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the panel border  |
| `--aa-panel-border-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the panel border |
| `--aa-input-border-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the input border  |
| `--aa-input-border-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the input border |

### Background colors

| Name                                                | Type                                                                                      | Description                                           |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `--aa-background-color-rgb`                         | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the background                         |
| `--aa-background-color-alpha`                       | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the background                        |
| `--aa-input-background-color-rgb`                   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the input background                   |
| `--aa-input-background-color-alpha`                 | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the input background                  |
| `--aa-selected-color-rgb`                           | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for selected, active, or focused elements  |
| `--aa-selected-color-alpha`                         | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for selected, active, or focused elements |
| `--aa-description-highlight-background-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the description highlight background   |
| `--aa-description-highlight-background-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the description highlight background  |

### Detached mode

| Name                              | Type                                                                                      | Description                                                                                                          |
| --------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `--aa-detached-media-query`       | [`media` query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries)       | Media query to enable [detached mode](/doc/ui-libraries/autocomplete/core-concepts/detached-mode) on smaller devices |
| `--aa-detached-modal-media-query` | [`media` query](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries)       | Media query to enable detached mode on bigger devices                                                                |
| `--aa-detached-modal-max-width`   | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                       | Maximum modal width in detached mode                                                                                 |
| `--aa-detached-modal-max-height`  | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                       | Maximum modal height in detached mode                                                                                |
| `--aa-overlay-color-rgb`          | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the overlay                                                                                           |
| `--aa-overlay-color-alpha`        | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the overlay                                                                                          |

### Shadows

| Name                | Type                                                                        | Description          |
| ------------------- | --------------------------------------------------------------------------- | -------------------- |
| `--aa-panel-shadow` | [`box-shadow`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow) | Shadow for the panel |

### Scrollbar

| Name                                          | Type                                                                                      | Description                         |
| --------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| `--aa-scrollbar-width`                        | [`length`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)                       | Scrollbar width                     |
| `--aa-scrollbar-track-background-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the scrollbar track  |
| `--aa-scrollbar-track-background-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the scrollbar track |
| `--aa-scrollbar-thumb-background-color-rgb`   | [`integer`](https://developer.mozilla.org/en-US/docs/Web/CSS/integer),`integer`,`integer` | RGB values for the scrollbar thumb  |
| `--aa-scrollbar-thumb-background-color-alpha` | [`number`](https://developer.mozilla.org/en-US/docs/Web/CSS/number)                       | Alpha value for the scrollbar thumb |

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

```css CSS icon=paintbrush theme={"system"}
: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`](/doc/ui-libraries/autocomplete/core-concepts/templates#param-templates-item) template.

<CodeGroup>
  ```js JavaScript theme={"system"}
  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>`;
      },
    },
  });
  ```

  ```jsx JSX theme={"system"}
  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>
        );
      },
    },
  });
  ```
</CodeGroup>

### 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**.

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

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

### Header

Here's the markup for a [`header`](/doc/ui-libraries/autocomplete/core-concepts/templates#param-templates-header) template.

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

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

### No results

Here's the markup for a [`noResults`](/doc/ui-libraries/autocomplete/core-concepts/templates#param-templates-no-results) template.

```js JavaScript icon=code theme={"system"}
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" />`