Combobox

Preview

<esa-combobox label="State" placeholder="Pick a state"></esa-combobox>

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-combobox';

@Component({
  selector: 'app-combobox-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-combobox label="State" placeholder="Pick a state"></esa-combobox>
  `,
})
export class ComboboxDemo {}

Combobox or Select?

If the user types into it, it is a Combobox. If they pick from what you gave them, it is a Select.

• Combobox — an input with suggestions. Filters as you type, highlights the match, and can fetch remotely: debounced search, loading, results-count.
• Select — a button opens a list, no text entry. Distant options are reached by typeahead.

mode and trigger-style are deprecated. mode="select" rendered a button trigger over a fixed list — that is a Select, under this component's name — and it was the default until 2026-08-15, so the default combobox was a select. Both still work and warn at runtime; trigger-style only ever styled that button trigger.

Sizes

<esa-combobox label="Extra small" size="xs"></esa-combobox>
<esa-combobox label="Small" size="sm"></esa-combobox>
<esa-combobox label="Medium" size="md"></esa-combobox>
<esa-combobox label="Large" size="lg"></esa-combobox>

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-combobox';

@Component({
  selector: 'app-combobox-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-combobox label="Extra small" size="xs"></esa-combobox>
    <esa-combobox label="Small" size="sm"></esa-combobox>
    <esa-combobox label="Medium" size="md"></esa-combobox>
    <esa-combobox label="Large" size="lg"></esa-combobox>
  `,
})
export class ComboboxDemo {}

States

Multi-select renders chips. Loading, results-count, error, and disabled states are attribute-driven.

<esa-combobox label="States visited" multiple placeholder="Add states"></esa-combobox>
<esa-combobox label="With results count" results-count="50" help-text="Shows 'Displaying X of Y results'"></esa-combobox>
<esa-combobox label="Loading" loading></esa-combobox>
<esa-combobox label="Error" error-text="Selection required"></esa-combobox>
<esa-combobox label="Disabled" disabled></esa-combobox>

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@esa/ecology/esa-combobox';

@Component({
  selector: 'app-combobox-demo',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <esa-combobox label="States visited" multiple placeholder="Add states"></esa-combobox>
    <esa-combobox
      label="With results count"
      results-count="50"
      help-text="Shows 'Displaying X of Y results'"
    ></esa-combobox>
    <esa-combobox label="Loading" loading></esa-combobox>
    <esa-combobox label="Error" error-text="Selection required"></esa-combobox>
    <esa-combobox label="Disabled" disabled></esa-combobox>
  `,
})
export class ComboboxDemo {}

API

Events

Accessibility

• Autocomplete input carries role="combobox" with aria-expanded, aria-haspopup="listbox", and aria-autocomplete="list".
• Panel is role="listbox"; options are role="option" with aria-selected.
• Keyboard: ArrowUp/Down navigate, Enter selects, Escape/Tab close. Outside-click closes.
• Matched substrings are wrapped in <mark> for visible highlight.
• Form-associated via ElementInternals — value submits with the enclosing form.

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.