Combobox New Alpha Light DOM & Tailwind

Usage

Combobox lets people choose one option (or several) from a list by typing to filter, then picking with the keyboard or pointer. Reach for it when a Select would be unwieldy because there are many options to scan.

Combobox renders its built-in label, hint and error on its own. Wrapped in a Field, the Field takes over with a Field Label, Field Description and Field Error, and the built-in versions step aside automatically.

Import the combobox; add the option parts when you author options declaratively (importing the combobox also registers them):

import "@nordhealth/components/lib/Combobox"
import "@nordhealth/components/lib/ComboboxOption"
import "@nordhealth/components/lib/ComboboxGroup"

Options can be authored declaratively as child elements or set as a data array — see Composition.

For a free-text input with suggestions (where the typed text is the value), see Autocomplete.

Standalone or inside a Field

Use the control on its own with its built-in label, hint and error, or wrap it in a Field — the Field then provides the labelling. Both render the same control:

Composition

There are two ways to supply options. Author them declaratively as children of <nord-combobox>, like a native <select> — no JavaScript required — or set the .options property for dynamic data.

Combobox
├── ComboboxOption
├── ComboboxOption
└── ComboboxGroup        (optional)
    ├── ComboboxOption
    └── ComboboxOption

<nord-combobox>
  <nord-combobox-option value="next">Next.js</nord-combobox-option>
  <nord-combobox-group label="Meta-frameworks">
    <nord-combobox-option value="astro">Astro</nord-combobox-option>
  </nord-combobox-group>
</nord-combobox>

Combobox Option

<nord-combobox-option> declares a single option:

• value — the value submitted with the form and tracked in the combobox's value.
• disabled — marks the option unselectable; it stays visible but is skipped during keyboard navigation.
• label — text used for filtering and the accessible name. Defaults to the element's text content.

The option's child markup becomes the rendered row, so you can author custom items — an avatar, secondary text, an icon — without an html string or a render function. Set label when the content isn't plain text, so filtering and the accessible name have something to match on.

Combobox Group

<nord-combobox-group label="…"> clusters the <nord-combobox-option> children inside it under a heading; each contained option inherits the group's label.

Combobox
└── ComboboxGroup        (label)
    ├── ComboboxOption
    └── ComboboxOption

Data-driven options

For dynamic, async or very large (virtualized) lists, set the .options property — an array of { value, label } objects — instead of declaring children. It's bound like any framework prop: :options in Vue, options={} in React, .options=${} in Lit. When .options is set it takes precedence over any declarative children.

Examples

Multiple

Add multiple to select several options. Selected options appear as removable chips. Pair it with clearable when users need to clear all selected chips at once. Set the initial selection with the .value property as an array.

Creatable

Add creatable to offer the typed query as a new option. When the query doesn't match an existing option, a highlighted "Create" row (hinted with a ⏎ Kbd) appears; selecting it adds the value as an option and selects it automatically — no JavaScript required. A create event still fires for notification; call event.preventDefault() in the handler to opt out and add the option yourself (for example, to map the typed text to a different value).

Async search

Add external-filtering to take over filtering yourself — listen for input, fetch matches, and assign them to .options. Set loading to show a spinner while the request is in flight. A preselected value keeps its label even before its option has loaded.

Async search (multiple)

The same async pattern works with multiple: selections become chips while typing fetches fresh matches. Use clearable to offer one-step clearing for the selected chips.

Virtualized

Add virtualized for very large lists. The combobox renders only the options in view (windowing), so a list of thousands stays fast. Rows are assumed to be a uniform height; virtualization is skipped for grouped lists.

Clearable

A clear (✕) button is shown by default whenever there is a value. Set the clearable property to false (e.g. .clearable = false, or :clearable="false" / clearable={false} in a framework) to hide it. The button only controls that affordance — a single-select value can always be cleared by deleting the input text.

Grouped options

Cluster related options under a heading: wrap declarative options in a <nord-combobox-group label="…">, or give each .options entry a group.

Auto highlight

Add auto-highlight to highlight the first matching option as the user types, so it can be committed by pressing Enter.

Invalid

Mark the surrounding Field as invalid to show the error state.

Custom items

For declarative options, author custom content as markup inside <nord-combobox-option> (see Composition). For data-driven .options, provide a .renderOption function (or a per-option html string) to render richer rows.

Disabled items

Mark individual options with disabled to keep them visible but unselectable. They are skipped during keyboard navigation.

Readonly

Set readonly to show the current value while preventing edits. The control stays focusable so its value can still be read, but the list cannot be opened.

Open on focus

By default the list opens when the combobox receives focus. Set open-on-focus to false to require a keystroke or click before the list appears.

Input group

Combobox composes inside an Input Group so you can pair it with buttons or other controls as a single unit.

Preselected value

Set the .value property to preselect an option. The combobox shows its label on load, even before the user opens the list.

Inside a dialog

Combobox positions its list correctly when used inside a Modal or other dialog, so the options are never clipped by the dialog bounds.

RTL

Combobox follows the document or container direction. Toggle the direction to see the layout mirror.

Accessibility

• Give Combobox an accessible name with its built-in label, or — inside a Field — a Field Label; use Field Error for validation messages.
• The list, active option and selection state are wired up with ARIA, and the highlighted option is tracked with aria-activedescendant so screen reader users hear the current choice while filtering.
• The full keyboard pattern is supported: type to filter, move through options with the arrow keys, commit with Enter, and dismiss the list with Escape.
• When clearable is set, the clear button has an accessible label so its purpose is announced.