Skip to content

Combobox ​

An autocomplete input that combines a text field with a filterable dropdown listbox. Users can type to narrow the displayed options or use arrow keys to browse, making it ideal for long option lists. Filtered options glide to their new slots with the same reflow motion as the command palette (animateReflow), so a narrowing list keeps its context.

Basic Usage ​

Place <ore-combobox-option> elements inside <ore-combobox>. The value attribute is what gets submitted; the text content is the label used for display and filtering.

Full width

Variants ​

Five visual variants for different UI contexts and levels of emphasis.

Full width

Options with Icons ​

Add an icon named slot inside any <ore-combobox-option> for a leading icon. The icon is rendered in the dropdown alongside the label.

Full width

Colors ​

Full width

Sizes ​

Full width

Label Placement ​

The label can be placed inset (inside the field, above the input: default) or outside (above the field border). Use hide-label only when surrounding context and placeholder text make the purpose clear; the label remains the combobox's accessible name.

Full width

Clearable ​

Add clearable to show a clear (×) button whenever a value is selected. Use this when the field is optional and users might want to reset their choice.

Full width

Multiselect ​

Add multiple to allow selecting more than one option. Each selected value is shown as a removable ore-chip inside the field. Pressing Backspace on an empty input removes the last chip. By default only the first three chips are shown; the rest collapse into a +N chip. Set max-visible to change the cap, or 0 to show every chip.

Full width

In multiple mode the change event detail includes both value (comma-separated) and values (array):

js
document.querySelector('ore-combobox').addEventListener('change', (e) => {
  console.log('value:', e.currentTarget.value); // ["ts", "rust", "go"] in multiple mode
});

Slotted content in the footer slot renders pinned under the option list inside the dropdown. Keep actions light — the footer sits in the scrolling panel, so a couple of buttons is the design budget.

Full width

Helper & Error Text ​

Pair error text with color="error" for form validation feedback.

Full width

Disabled Options ​

Add the disabled attribute on a <ore-combobox-option> to prevent selection. Add disabled-reason to explain why the choice is unavailable; the reason remains visible and is included in the option's accessible name.

Full width

The JavaScript options property uses the camelCase equivalent:

js
combobox.options = [{ value: 'viewer', label: 'Viewer', disabled: true, disabledReason: 'Requires editor access' }];

Disabled State ​

Full width

Set no-filter to keep all options visible regardless of what the user types. Use this when filtering happens server-side: replace the <ore-combobox-option> children based on the search event. For short lists (fewer than 6 items) consider a plain ore-select instead.

Full width

For a real server-side integration, replace options dynamically on search:

js
const cb = document.getElementById('user-cb');
cb.addEventListener('search', async (e) => {
  const results = await fetch(`/api/users?q=${encodeURIComponent(e.detail.query)}`).then((r) => r.json());
  cb.querySelectorAll('ore-combobox-option').forEach((el) => el.remove());
  for (const user of results) {
    const opt = document.createElement('ore-combobox-option');
    opt.setAttribute('value', user.id);
    opt.textContent = user.name;
    cb.appendChild(opt);
  }
});

Creatable Options ​

Add creatable to allow users to create a new option when their query does not match any existing option. A Create "X" button appears at the bottom of the dropdown. Selecting it adds the new option and emits a ore-change event like any normal selection.

Full width
js
document.querySelector('ore-combobox').addEventListener('change', (e) => {
  // Both selected and newly created options fire change
  console.log('Selected/created:', e.currentTarget.value);
});

Custom Labels ​

Built-in strings live in the labels JavaScript property. Override only what you need — anything unset keeps its default. Use it for localization or rewording.

js
const combobox = document.querySelector('ore-combobox');

combobox.labels = {
  noResults: 'Rien trouvé',
  create: (query) => `Ajouter « ${query} »`,
};
KeyTypeDefaultWhere it appears
noResultsstring'No results found'Empty-state row in the dropdown
create(query: string) => stringCreate "X"Creatable row (only offered for new terms)

Loading State ​

Set loading to show a loading indicator inside the dropdown while options are being fetched. Use this together with no-filter for server-side search.

Full width
js
const cb = document.querySelector('ore-combobox');
cb.addEventListener('search', async (e) => {
  cb.loading = true;
  const results = await fetch(`/api/items?q=${encodeURIComponent(e.detail.query)}`).then((r) => r.json());
  cb.options = results.map((r) => ({ value: r.id, label: r.name }));
  cb.loading = false;
});

JavaScript Options ​

Set the options property directly in JavaScript to provide options without using <ore-combobox-option> children. Each item only needs a value; label falls back to the same string when omitted, while disabled remains optional.

js
const cb = document.querySelector('ore-combobox');
cb.options = [{ value: 'ts' }, { value: 'rust', label: 'Rust' }, { value: 'go', label: 'Go', disabled: true }];

Assigning a new array to options updates the dropdown immediately. When both <ore-combobox-option> children and options are present, the JS property takes precedence.

In a Form ​

ore-combobox is form-associated: its name attribute participates in native FormData submissions. Set required to fail constraint validation while nothing is selected: a native <form> blocks submission and checkValidity()/reportValidity() return false until an option is chosen; resetting the ancestor form restores the initial selection.

Full width
js
document.getElementById('myForm').addEventListener('submit', (e) => {
  e.preventDefault();
  const data = new FormData(e.target);
  console.log('country:', data.get('country'));
});

Listening to Events ​

Full width
js
const cb = document.getElementById('my-cb');

// Fired when a value is selected from the list
cb.addEventListener('change', (e) => {
  console.log('value:', e.currentTarget.value);
  // In multiple mode, value is a string array.
});

// Fired on every keystroke in the input
cb.addEventListener('search', (e) => {
  console.log('query:', e.detail.query);
});

cb.addEventListener('open-change', (e) => {
  console.log('dropdown open:', e.detail.open, e.detail.reason);
});

API Reference ​

ore-combobox Attributes

AttributeTypeDefaultDescription
valuestring''Currently selected value
namestring''Form field name
labelstring''Label text
label-placement'inset' | 'outside''inset'Label positioning
hide-labelbooleanfalseHide the visual label while retaining its accessible name
placeholderstring''Input placeholder text
helperstring''Helper text shown below the field
errorstring''Error message; overrides helper text
color'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error'N/AColor theme
variant'solid' | 'flat' | 'bordered' | 'outline' | 'ghost''solid'Visual style variant
size'sm' | 'md' | 'lg''md'Field size
rounded'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'full'N/ABorder radius override
clearablebooleanfalseShow a clear button when a value is selected
no-filterbooleanfalseDisable client-side option filtering (for server-side use)
creatablebooleanfalseShow a "Create X" option when no match is found
loadingbooleanfalseShow a loading indicator in the dropdown
multiplebooleanfalseAllow selecting multiple options (chips are shown in field)
max-visiblenumber3Chips shown before the +N overflow chip (0 = unlimited)
fullwidthbooleanfalseExpand to fill the container width
disabledbooleanfalseDisable the control
requiredbooleanfalseRequire a non-blank selection for native-form validation

ore-combobox Slots

SlotDescription
(default)ore-combobox-option elements defining the option list
footerOptional content pinned under the option list inside the panel

ore-combobox JavaScript Properties

PropTypeDefaultDescription
labelsPartial<ComboboxLabels>see Custom LabelsOverrides for built-in noResults/create text

ore-combobox-option Attributes

AttributeTypeDefaultDescription
valuestring''The value submitted to the form and emitted in ore-change
labelstringN/AExplicit text used for display and filtering; falls back to the element's textContent
disabledbooleanfalsePrevent this option from being selected

ore-combobox-option Slots

SlotDescription
iconOptional leading icon or decoration
(default)Label text for the option

Events

EventDetailDescription
change{ value: string, values: string[], labels: string[], originalEvent?: Event }Emitted when selected value(s) change
open-change{ open: boolean, reason: string }Emitted whenever the dropdown opens or closes
search{ query: string }Emitted on every keystroke in the text input

CSS Custom Properties

PropertyDescriptionDefault
--combobox-dropdown-bgDropdown panel background colorTheme-dependent
--combobox-dropdown-border-colorDropdown panel border colorTheme-dependent
--combobox-option-hover-bgOption background on hoverTheme-dependent
--combobox-option-focus-bgOption background when keyboard-focusedTheme-dependent
--combobox-option-selected-bgOption background when selectedTheme-dependent
--combobox-option-selected-focus-bgOption background when selected and focusedTheme-dependent
--input-bgField background (passed through to ore-input)Variant-dependent
--input-border-colorField border color (passed through to ore-input)Variant-dependent

Accessibility ​

The combobox component follows WCAG 2.1 Level AA standards. Keyboard navigation is fully supported: Tab focuses the input, ArrowDown / ArrowUp navigate the option list, Enter confirms selection, and Escape closes the dropdown.

The component uses role="combobox" with aria-expanded, aria-controls, aria-activedescendant, and aria-autocomplete="list". The dropdown uses role="listbox"; each option uses role="option" with aria-selected and aria-disabled. An aria-live="polite" region on the helper / error area announces validation messages. aria-labelledby links the label; aria-describedby links helper and error text. aria-disabled reflects the disabled state.