---
url: /docs/components/combo-box/frameworks/elements.md
---
# 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.
## 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
Norway
Sweden
Denmark
```
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
Norway
Sweden
Denmark
```
When the combobox is invalid, pair `invalid` with help text that explains how to correct the error.
```html
Norway
Sweden
Denmark
```
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
US
UK
Norway
```
### 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 `` elements for declarative HTML usage.
```html
Norway
Sweden
Denmark
```
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 ` ` elements.
## Examples
```html
Apple
Banana
Orange
```
### Different label and value
Use the `label` attribute when the visible suggestion should differ from the selected value.
```html
US
UK
Norway
```
### 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
Combobox supports styling through **component tokens** (CSS custom properties with a `--w-c-` prefix) and **parts**.
### Parts
The combobox exposes a set of parts that can be targeted for last-mile layout or typography tweaks. Since the combobox uses a w-textfield internally, parts exposed by the textfield can also be styled. If you use the `tooltip` property, the tooltip component's parts can also be styled. All stylable parts are listed in the table below.
Use `::part(part-name)` from outside the component.
| Part | Targets | Typical use |
|---|---|---|
| `base` | wrapper around the component internals | |
| `textfield-wrapper` | wrapper around the textfield component internals | |
| `input` | native input element | minor typography or spacing tweaks |
| `mask-wrapper` | wrapper around the input mask | formatting-related layout tweaks |
| `mask` | formatted value shown when the input is not focused | typography for formatter output |
| `help-text` | help text container below the field | small typography tweaks |
| `label` | label element above the field | small label layout tweaks |
| `tooltip-target` | info icon button rendered when `tooltip` is set | small icon button alignment tweaks |
| `tooltip` | tooltip surface exported by `w-tooltip` | tooltip surface tweaks |
| `arrow` | tooltip arrow exported by `w-tooltip` | tooltip arrow tweaks |
| `beak` | tooltip beak exported by `w-tooltip` | tooltip beak tweaks |
| `hover-bridge` | tooltip hover bridge exported by `w-tooltip` | tooltip hover behavior tweaks |
| `options-list` | options list popover | popover background, shadow, spacing, or radius tweaks |
| `option` | individual option in the listbox | option spacing, typography, or state tweaks |
```css
w-combobox::part(base) {
padding: 48px;
background: rebeccapurple;
color: cyan;
}
```
### Combobox tokens
Set these on `` to override visuals.
```css
w-combobox {
--w-c-combobox-color-background: hotpink;
}
```
#### Textfield tokens
| Token | Purpose | Default |
|---|---|---|
| `--w-c-textfield-padding-left` | input left padding | `8px` |
| `--w-c-textfield-padding-right` | input right padding | `8px` |
| `--w-c-textfield-line-height` | input line height | `--w-line-height-m` |
| `--w-c-textfield-font-size` | input font size | `--w-font-size-m` |
| `--w-c-textfield-color-border` | border color | `--w-s-color-border-strong` |
| `--w-c-textfield-color` | input text color | `--w-s-color-text` |
| `--w-c-textfield-background` | input background color | `--w-s-color-background` |
| `--w-c-textfield-color-border-active` | border color while active | `--w-s-color-border-selected` |
| `--w-c-textfield-color-border-hover` | border color on hover | `--w-s-color-border-strong-hover` |
| `--w-c-textfield-outline-focus` | focus outline | `2px solid var(--w-s-color-border-focus)` |
| `--w-c-textfield-outline-offset` | focus outline offset | `-2px` |
| `--w-c-textfield-color-border-invalid` | border color when invalid | `--w-s-color-border-negative` |
| `--w-c-textfield-color-invalid` | text color when invalid | `--w-s-color-text-negative` |
| `--w-c-textfield-outline-invalid` | outline when invalid | `2px solid var(--w-s-color-border-negative)` |
| `--w-c-textfield-color-border-invalid-hover` | border color when invalid and hovered | `--w-s-color-border-negative-hover` |
| `--w-c-textfield-color-border-disabled` | border color when disabled | `--w-s-color-border-disabled` |
| `--w-c-textfield-color-disabled` | text color when disabled | `--w-s-color-text-disabled` |
| `--w-c-textfield-color-background-disabled` | background color when disabled | `--w-s-color-background-disabled-subtle` |
| `--w-c-textfield-color-placeholder` | placeholder text color | `--w-s-color-text-placeholder` |
#### Label tokens
| Token | Purpose | Default |
|---|---|---|
| `--w-c-input-label-color` | label text color | `--w-s-color-text` |
| `--w-c-input-label-font-size` | label font size | `--w-font-size-s` |
| `--w-c-input-label-line-height` | label line height | `--w-line-height-s` |
| `--w-c-input-label-font-weight` | label font weight | `700` |
| `--w-c-input-label-padding-bottom` | space below label | `0.4rem` |
| `--w-c-input-label-cursor` | cursor when hovering label | `pointer` |
| `--w-c-input-label-display` | label display mode | `block` |
#### Optional indicator tokens
When the `optional` attribute is set and the field is not `required`, these tokens control the optional indicator after the label.
| Token | Purpose | Default |
|---|---|---|
| `--w-c-input-optional-color` | optional text color | `--w-s-color-text-subtle` |
| `--w-c-input-optional-font-size` | optional text font size | `--w-font-size-s` |
| `--w-c-input-optional-line-height` | optional text line height | `--w-line-height-s` |
| `--w-c-input-optional-font-weight` | optional text font weight | `400` |
| `--w-c-input-optional-padding-left` | space before optional text | `0.4rem` |
#### Help text tokens
| Token | Purpose | Default |
|---|---|---|
| `--w-c-input-help-text-color` | help text color | `--w-s-color-text-subtle` |
| `--w-c-input-help-text-color-invalid` | help text color when invalid | `--w-s-color-text-negative` |
| `--w-c-input-help-text-font-size` | help text font size | `--w-font-size-xs` |
| `--w-c-input-help-text-line-height` | help text line height | `--w-line-height-xs` |
| `--w-c-input-help-text-margin-top` | space above help text | `0.4rem` |
| `--w-c-input-help-text-display` | help text display mode | `block` |
#### Tooltip tokens
| Token | Purpose | Default |
|---|---|---|
| `--w-c-tooltip-z-index` | tooltip stack order | `30` |
| `--w-c-tooltip-bg` | tooltip background color | `--w-s-color-background-inverted-static` |
| `--w-c-tooltip-color` | tooltip text color | `--w-s-color-text-inverted-static` |
| `--w-c-tooltip-box-shadow` | tooltip shadow | `--w-shadow-m` |
#### Options list tokens
| Token | Purpose | Default |
|---|---|---|
| `--w-c-combobox-padding-bottom` | space below the options list | `0.4rem` |
| `--w-c-combobox-shadow` | options list shadow | `--w-shadow-m` |
| `--w-c-combobox-color-background` | options list background color | `--w-s-color-background` |
| `--w-c-combobox-border-radius` | options list border radius | `8px` |
| `--w-c-combobox-option-padding` | option padding | `0.8rem` |
| `--w-c-combobox-option-color-background-hover` | option background color on hover | `--w-s-color-background-hover` |
| `--w-c-combobox-option-color-background-selected` | selected option background color | `--w-s-color-background-selected` |
| `--w-c-combobox-options-box-z-index` | options-list stacking order | `20` |
## `` 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 `` 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: `""`
### Types
#### MutationObserver | undefined
`{ disconnect: { }, observe: { }, takeRecords: { } } | undefined`