Guide

Style it your way

Theme the optional stylesheet with CSS custom properties or style the list, options and states through a small data-attribute contract.

Import the optional stylesheet once:

import '@samline/autocomplete/style.css'

DOM contract

<input role="combobox" … />
<div data-autocomplete-popup data-placement="bottom">
  <div data-autocomplete-header>…</div>
  <div role="listbox" data-autocomplete-list>
    <div role="group" data-autocomplete-group="cities" aria-labelledby="…">
      <div role="presentation" data-autocomplete-group-label>Cities</div>
      <div role="option" data-autocomplete-option data-active="true">
        <mark data-autocomplete-highlight>Mér</mark>ida
      </div>
    </div>
  </div>
  <div data-autocomplete-footer>…</div>
  <div data-autocomplete-status="empty">No results</div>
</div>
<div role="status" data-autocomplete-live>1 result available</div>
<input type="hidden" name="city_id" data-autocomplete-hidden />
Selector What it is
[data-autocomplete-popup] The positioned container, placed right after the input
[data-autocomplete-list] The listbox inside the popup
[data-placement='bottom' | 'top'] The side the popup opened on
[data-autocomplete-group] A section group (its value is the section id)
[data-autocomplete-group-label] A section heading
[data-autocomplete-header], [data-autocomplete-footer] renderHeader and renderFooter containers
[data-autocomplete-hidden] A hidden input created by hiddenInput
[data-autocomplete-option] One suggestion
[data-active='true'] The keyboard or pointer highlighted option
[data-autocomplete-highlight] A matching part of the label (a <mark>)
[data-autocomplete-status='loading' | 'empty' | 'error'] The visible request state, outside the listbox
[data-autocomplete-live] The visually hidden live region, styled inline

The popup, list, status, header and footer use the native hidden attribute while closed. With popover: true the popup also gets popover="manual" and inline fixed coordinates.

Custom properties

.search-field {
  --autocomplete-background: #111827;
  --autocomplete-color: #f9fafb;
  --autocomplete-active-background: #374151;
  --autocomplete-border: #4b5563;
  --autocomplete-radius: 0.75rem;
  --autocomplete-max-height: 20rem;
}

Also available: --autocomplete-z-index, --autocomplete-offset, --autocomplete-shadow, --autocomplete-option-padding, --autocomplete-active-color, --autocomplete-muted-color, --autocomplete-error-color, --autocomplete-highlight-background (transparent), --autocomplete-highlight-color (inherit) --autocomplete-highlight-weight (600), --autocomplete-group-padding and --autocomplete-group-font-size. In forced-colors mode the active option gets a system-color outline.

Richer options

renderOption(option, suggestion, context) receives the created option, already filled with the highlighted label, and { query, index, label, highlight }. Append elements instead of setting HTML strings, so suggestion data is never parsed as markup. To restructure the option, empty it and reuse the highlight:

import { renderHighlight } from '@samline/autocomplete'

const renderOption = (option, city, { highlight }) => {
  option.replaceChildren()
  const name = document.createElement('strong')
  renderHighlight(name, highlight)
  const country = document.createElement('small')
  country.textContent = city.country
  option.append(name, country)
}