# Combobox (w-combobox)

## Description

A combobox element for text input with selectable options.

[Warp component reference](https://warp-ds.github.io/docs/components/combo-box/frameworks/elements)

## Usage

Use child `<option>` elements for declarative HTML usage.

<elements-example>

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

</elements-example>

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.

```js
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.

## 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.

## Examples

<elements-example>

```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>
```

</elements-example>

### Different label and value

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

<elements-example>

```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>
```

</elements-example>

### Dynamic options

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

```js
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. |
| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
| select-on-blur | `boolean` | `true` | Whether the active option is selected when the input loses focus. |
| tooltip | `string \| undefined` | `-` | Supplementary information that should show in a tooltip behind an information icon after the label. |
| 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`

#### resetFormControl (JS only)



- Type: `resetFormControl() => void`
- Default: `-`

#### 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`

#### tooltip

Supplementary information that should show in a tooltip behind an information icon after the label.

You must provide a label to be able to show an info icon with a tooltip.

- Type: `string | undefined`
- Default: `-`

#### 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: `""`