# Combobox

> Source: https://design.nanatec.co.ke/components/combobox/
> An editable text field paired with a filterable listbox. Type to filter the `nana-option` children, then pick a value with the keyboard or pointer. The panel flips above the field when it would overflow the viewport.

An editable text field paired with a filterable listbox. Type to filter the `nana-option` children, then pick a value with the keyboard or pointer. The panel flips above the field when it would overflow the viewport.

## Preview

```html
<nana-combobox label="Fruit" placeholder="Search…" style="min-width:16rem">
  <nana-option value="apple">Apple</nana-option>
  <nana-option value="banana">Banana</nana-option>
</nana-combobox>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/combobox";
```

## Basic usage

```html
<nana-combobox label="Fruit" placeholder="Search…" style="min-width:16rem">
  <nana-option value="apple">Apple</nana-option>
  <nana-option value="banana">Banana</nana-option>
</nana-combobox>
```

## With a prefix icon

Slot an icon into the `prefix` slot; `clearable` adds a reset button.

```html
<nana-combobox label="Search country" placeholder="Type to filter…" clearable style="min-width:16rem">
  <nana-icon slot="prefix" name="search"></nana-icon>
  <nana-option value="us">United States</nana-option>
  <nana-option value="ca">Canada</nana-option>
  <nana-option value="mx">Mexico</nana-option>
</nana-combobox>
```

## API

## Events

| Event | Type | Description |
|---|---|---|
| `nana-input` | `CustomEvent` | Fired while typing (`detail.value` — the query text) |
| `nana-change` | `CustomEvent` | Fired when an option is selected (`detail.value`) |
| `nana-clear` | `CustomEvent` | Fired when the field is cleared |
| `nana-focus` | `CustomEvent` | Fired on focus |
| `nana-blur` | `CustomEvent` | Fired on blur |

## Slots

| Slot | Description |
|---|---|
| `(default)` | `nana-option` children |
| `prefix` | Leading icon inside the field |

## CSS Variables

| Variable | Default | Description |
|---|---|---|
| `--nana-combobox-max-height` | — | Panel max height before scrolling |

## CSS Parts

| Part | Description |
|---|---|
| `wrapper` | The bordered field container |
| `input` | The native `<input>` element |
| `panel` | The floating listbox panel |

## Accessibility

<ul class="a11y-grid not-content">
  <li>Keyboard accessible</li>
  <li>Screen-reader labels</li>
  <li>Focus-visible states</li>
  <li>ARIA roles and states</li>
  <li>WCAG 2.2 AA contrast</li>
</ul>

## Related components

<ul class="related not-content">
  <li><a href="/components/button/">Button</a></li>
  <li><a href="/components/button-group/">Button Group</a></li>
  <li><a href="/components/icon-button/">Icon Button</a></li>
  <li><a href="/components/input/">Input</a></li>
  <li><a href="/components/textarea/">Textarea</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-combobox--docs