# Combobox
{"No results found."} {"Astro"} {"Next.js"} {"Nuxt"} {"Remix"} {"SvelteKit"}
```astro --- --- No results found. Astro Next.js Nuxt Remix SvelteKit ``` ## Installation ```bash bunx bejamas add combobox ``` ```bash npx bejamas add combobox ``` ```bash pnpm dlx bejamas add combobox ``` ```bash yarn dlx bejamas add combobox ``` ## Usage ```astro nocollapse --- --- No results found. Astro Next.js ``` ## Props | Prop | Type | Default | |---|---|---| | class | `string` | `""` | | name | `string` | | | defaultValue | `string` | | | placeholder | `string` | | | disabled | `boolean` | `false` | | required | `boolean` | `false` | | openOnFocus | `boolean` | | | autoHighlight | `boolean` | | ## Examples ### Clear Button Use the `showClear` prop to show a clear button in the input.
{"No results found."} {"Astro"} {"Next.js"} {"Nuxt"} {"Remix"}
```astro --- --- No results found. Astro Next.js Nuxt Remix ``` ### Sizing Use the `size` prop on `ComboboxInput` to match button/input sizing.
{"Astro"} {"Next.js"} {"Astro"} {"Next.js"} {"Astro"} {"Next.js"}
```astro --- ---
Astro Next.js Astro Next.js Astro Next.js
``` ### Groups Use the `ComboboxGroup` and `ComboboxLabel` to group items and add a label to the group.
{"No results found."} {"Frontend"} {"Astro"} {"Next.js"} {"Nuxt"} {"Backend"} {"Express"} {"Hono"}
```astro --- --- No results found. Frontend Astro Next.js Nuxt Backend Express Hono ``` ### Invalid Use the `aria-invalid="true"` attribute on the `ComboboxInput` to mark the combobox as invalid.
{"Astro"} {"Next.js"}
```astro --- --- Astro Next.js ``` ### Disabled Use the `disabled` prop to disable the combobox.
{"Astro"} {"Next.js"}
```astro --- --- Astro Next.js ``` ### Auto Highlight Use the `autoHighlight` prop to automatically highlight the first item on filter.
{"No results found."} {"Astro"} {"Next.js"} {"Nuxt"} {"Remix"}
```astro --- --- No results found. Astro Next.js Nuxt Remix ``` ### Search in Popup You can trigger the combobox from a button or any other component by using the render prop. Move the `ComboboxInput` inside the `ComboboxContent`.
{"No countries found."} {"Brazil"} {"Canada"} {"France"} {"Germany"} {"Japan"}
```astro --- --- No countries found. Brazil Canada France Germany Japan ``` ## API Reference ### Events The combobox emits custom events that you can listen to: | Event | Detail | Description | |-------|--------|-------------| | `combobox:change` | `{ value: string \| null }` | Fired when a new value is selected | | `combobox:open-change` | `{ open: boolean }` | Fired when the dropdown opens or closes | | `combobox:input-change` | `{ inputValue: string }` | Fired when the user types in the input |
{"Option 1"} {"Option 2"}
```astro nocollapse Option 1 Option 2 ``` ```js nocollapse const combobox = document.getElementById('my-combobox'); combobox.addEventListener('combobox:change', (e) => { console.log('Selected value:', e.detail.value); }); combobox.addEventListener('combobox:input-change', (e) => { console.log('Input text:', e.detail.inputValue); }); ``` ### Programmatic Control You can control the combobox programmatically by dispatching a `combobox:set` event: ```js nocollapse const combobox = document.getElementById('my-combobox'); // Set a specific value combobox.dispatchEvent(new CustomEvent('combobox:set', { detail: { value: 'option2' } })); // Clear the value combobox.dispatchEvent(new CustomEvent('combobox:set', { detail: { value: null } })); // Open the dropdown combobox.dispatchEvent(new CustomEvent('combobox:set', { detail: { open: true } })); // Set the input text combobox.dispatchEvent(new CustomEvent('combobox:set', { detail: { inputValue: 'search term' } })); // Custom display text for selected value // itemToStringValue — (item: HTMLElement | null, value: string | null) => string // Controls what text appears in the input after selection. // Useful when items contain rich content (icons, descriptions). combobox.dispatchEvent(new CustomEvent('combobox:set', { detail: { itemToStringValue: (item, value) => value ? `TZ: ${value}` : '' } })); ``` ### Data Attributes The combobox sets these data attributes that you can use for styling or querying state: | Attribute | Element | Description | |-----------|---------|-------------| | `data-open` | combobox, combobox-content | Present when the popup is open | | `data-closed` | combobox, combobox-content | Present when the popup is closed | | `data-side` | combobox-content | Resolved popup side | | `data-align` | combobox-content | Resolved popup alignment | | `data-value` | combobox | Currently selected value | | `data-selected` | combobox-item | Present when item is selected | | `data-highlighted` | combobox-item | Present when item is focused/highlighted | | `data-disabled` | combobox, combobox-item | Present when disabled | | `data-empty` | combobox-content | Present when no items match the filter | ### Positioning Placement options are configured on `ComboboxContent`: ```astro nocollapse nopreview ... ```