Combo box - Elements

A combo box combines a dropdown list with an editable text input, allowing users to either select an option or type their own.

ElementsreleasedReactreleased

Example theme:

Accessibility

Combobox renders an input with role="combobox" and a popup list with role="listbox". Each suggestion is rendered with role="option", and the active suggestion is connected to the input with aria-activedescendant.

Provide A Label

Always provide a visible label.

html

<w-combobox label="Country" placeholder="Search">
  <option value="no">Norway</option>
  <option value="se">Sweden</option>
  <option value="dk">Denmark</option>
</w-combobox>

Do not rely on placeholder text as the only label. Placeholder text disappears as soon as the user types and is not a reliable accessible name.

Help Text And Errors

Use help-text for extra guidance or validation feedback.

html

<w-combobox label="Country" help-text="Start typing to filter countries">
  <option value="no">Norway</option>
  <option value="se">Sweden</option>
  <option value="dk">Denmark</option>
</w-combobox>

When the combobox is invalid, pair invalid with help text that explains how to correct the error.

html

<w-combobox label="Country" invalid help-text="Select a country from the list">
  <option value="no">Norway</option>
  <option value="se">Sweden</option>
  <option value="dk">Denmark</option>
</w-combobox>

Do not rely on invalid styling alone.

Keyboard Interaction

The input follows common combobox keyboard behavior:

Arrow Down and Arrow Up open the list and move between suggestions.
Home and End move to the first and last suggestion.
Page Up and Page Down move through suggestions in larger steps.
Enter selects the active suggestion.
Escape closes the list. When the list is already closed, Escape clears the value.
Tab closes the list and moves focus onward.

Suggestions

The component announces the number of available suggestions through a screen-reader-only status message while the list is open.

Keep option labels short and unique enough to distinguish. If the submitted value differs from what users should read, provide a clear option label.

html

<w-combobox label="Country" placeholder="Search">
  <option value="us" label="United States">US</option>
  <option value="uk" label="United Kingdom">UK</option>
  <option value="no">Norway</option>
</w-combobox>

Disabled Comboboxes

Avoid disabled comboboxes where possible. Disabled controls can be hard to discover and do not explain why the field is unavailable.

Prefer leaving the combobox enabled and showing validation or explanatory feedback when the user tries to continue.

Usage

Use child <option> elements for declarative HTML usage.

html

<w-combobox label="Country" placeholder="Search">
    <option value="no">Norway</option>
    <option value="se">Sweden</option>
    <option value="dk">Denmark</option>
</w-combobox>

The option text is used as the visible suggestion. The value attribute is used as the submitted and selected value.

For framework usage or dynamic data, you may set the options property instead.

combobox.options = [
  { value: 'no', label: 'Norway' },
  { value: 'se', label: 'Sweden' },
  { value: 'dk', label: 'Denmark' },
];

When options contains entries, it is used instead of child <option> elements.

Examples

html

<w-combobox label="Fruit" placeholder="Type to search">
    <option value="apple">Apple</option>
    <option value="banana">Banana</option>
    <option value="orange">Orange</option>
</w-combobox>

Different label and value

Use the label attribute when the visible suggestion should differ from the selected value.

html

<w-combobox label="Country" placeholder="Search">
    <option value="us" label="United States">US</option>
    <option value="uk" label="United Kingdom">UK</option>
    <option value="no">Norway</option>
</w-combobox>

Dynamic options

Use the options property when options come from application state or a remote search.

const combobox = document.querySelector('w-combobox');

combobox.options = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'orange', label: 'Orange' },
];

Child option content is plain text. Rich option content is not supported.

Styling API

`<w-combobox>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

Properties

Name	Type	Default	Summary
autocomplete	`string \| undefined`	`'off'`	The autocomplete attribute passed to the internal input.
disable-static-filtering	`boolean`	`false`	Whether built-in client-side filtering is disabled.
disabled	`boolean`	`false`	Whether the combobox is disabled.
help-text	`string \| undefined`	`''`	Help text displayed below the input.
invalid	`boolean`	`false`	Whether the combobox is visually invalid.
label	`string \| undefined`	`''`	The label displayed above the input.
match-text-segments	`boolean`	`false`	Whether matching text segments in options are highlighted.
name	`string \| undefined`	`''`	The name submitted with the combobox value.
open-on-focus	`boolean`	`false`	Whether the option list opens when the input receives focus.
optional	`boolean`	`false`	Whether to show optional text next to the label.
options	`ComboboxOption[]`	`[]`	The available options to select from.
placeholder	`string \| undefined`	`''`	Placeholder text displayed when the input is empty.
required	`boolean`	`false`	Whether the combobox is required before form submission.
select-on-blur	`boolean`	`true`	Whether the active option is selected when the input loses focus.
value	`string`	`''`	The selected or typed value.

Property Details

autocomplete

The autocomplete attribute passed to the internal input.

Defaults to off. Set this when browser autocomplete should be enabled or scoped to a specific autocomplete token.

Type: string | undefined
Default: 'off'

disable-static-filtering

Whether built-in client-side filtering is disabled.

Use this for remote search or externally filtered results. When disabled, all entries in options are rendered as provided.

Type: boolean
Default: false

disabled

Whether the combobox is disabled.

Disabled comboboxes cannot be focused, changed, or submitted with form data.

Type: boolean
Default: false

help-text

Help text displayed below the input.

Use this for supporting guidance or validation feedback.

Type: string | undefined
Default: ''

invalid

Whether the combobox is visually invalid.

Use this to show an externally managed validation error. Pair it with help-text to explain how to fix the error.

Type: boolean
Default: false

label

The label displayed above the input.

Use this to give the combobox a visible and accessible name.

Type: string | undefined
Default: ''

match-text-segments

Whether matching text segments in options are highlighted.

Use this to visually emphasize the part of each option that matches the current input value.

Type: boolean
Default: false

name

The name submitted with the combobox value.

Use this when the combobox belongs to a form and its value should be included in form data.

Type: string | undefined
Default: ''

open-on-focus

Whether the option list opens when the input receives focus.

Use this when users should see available options before they start typing.

Type: boolean
Default: false

optional

Whether to show optional text next to the label.

Use this to indicate that the combobox is not required.

Type: boolean
Default: false

options

The available options to select from.

Use this for framework usage, application state, or remote search results. When options contains entries, it is used instead of child <option> elements.

Type: ComboboxOption[]
Default: []

placeholder

Placeholder text displayed when the input is empty.

Use this as a short hint for the expected input. Do not use placeholder text as a replacement for a label.

Type: string | undefined
Default: ''

required

Whether the combobox is required before form submission.

Use this when the user must provide a value before submitting the form.

Type: boolean
Default: false

select-on-blur

Whether the active option is selected when the input loses focus.

When enabled, the combobox selects the keyboard-highlighted option, or an option whose value exactly matches the current input value, on blur.

Type: boolean
Default: true

value

The selected or typed value.

When an option is selected, this is set to the option value. The displayed text may differ when the option has a separate label.

Type: string
Default: ''

Questions?

Feel free to ask any questions on usage in the Warp DS Slack channel: #warp-design-system

Combo box - Elements ​

Accessibility ​

Provide A Label ​

Help Text And Errors ​

Keyboard Interaction ​

Suggestions ​

Disabled Comboboxes ​

Usage ​

Examples ​

Different label and value ​

Dynamic options ​

Styling API ​

<w-combobox> API ​

Properties ​

Property Details ​

autocomplete ​

disable-static-filtering ​

disabled ​

help-text ​

invalid ​

label ​

match-text-segments ​

name ​

open-on-focus ​

optional ​

options ​

placeholder ​

required ​

select-on-blur ​

value ​

Questions? ​

Combo box - Elements

Accessibility

Provide A Label

Help Text And Errors

Keyboard Interaction

Suggestions

Disabled Comboboxes

Usage

Examples

Different label and value

Dynamic options

Styling API

`<w-combobox>` API

Properties

Property Details

autocomplete

disable-static-filtering

disabled

help-text

invalid

label

match-text-segments

name

open-on-focus

optional

options

placeholder

required

select-on-blur

value

Questions?