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

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

