# `m-option-listbox`

An Option Listbox is a customizable, accessible listbox component designed to power dropdowns and comboboxes with advanced value capabilities. It supports single or multiple value, optional search, grouped options with section headers, and full keyboard navigation.

## Props

| Name | Description | Type | Default |
|------|-------------|------|---------|
| `value*` | The current selected value(s) of the listbox. | `string` `number` `null` `(string` `number)[]` | `$bindable()` |
| `id*` | Unique identifier for the listbox. | `string` |   |
| `open` | Whether the listbox is open. | `boolean` | `$bindable()` |
| `multiple` | Enable multiple value. | `boolean` |   |
| `readonly` | Make the listbox read-only. | `boolean` |   |
| `search` | Show a search input above the options. | `boolean` |   |
| `actions` | Show select all / clear buttons when multiple. | `boolean` |   |
| `checkablesections` | Enable checkable section headers. | `boolean` |   |
| `searchplaceholder` | Placeholder text for the search input. | `string` | `Find an option...` |
| `selectlabel` | Label for the "Select all" button. | `string` | `Select all` |
| `clearlabel` | Label for the "Clear value" button. | `string` | `Clear` |
| `options*` | Array of options and sections to display in the listbox. | `Array<ListboxOption>` |   |
| `onopen` | Callback to trigge when the listbox should open. | `() => void` |   |
| `onclose` | Callback to trigge when the listbox should close. | `() => void` |   |
| `activeindex*` |  | `number` | `$bindable()` |
| `element` |  | `HTMLElement` `null` | `$bindable()` |
| `item` |  | `Snippet<[{ option: ListboxOption }]>` |   |

## Events

| Name | Description | Type |
|------|------|-------------|
| `open` | Emits when the listbox should open. | `CustomEvent<void>` |
| `close` | Emits when the listbox should close. | `CustomEvent<void>` |

## Dependencies

### Depends on

- [m-button](../button/README.md)
- [m-textinput](../textinput/README.md)

### Graph

```mermaid
graph TD;
  m-option-listbox --> m-button
  m-option-listbox --> m-textinput
style m-option-listbox fill:#008240,stroke:#333,stroke-width:4px
```

### Used By

- [m-combobox](../combobox/README.md)

### Graph

```mermaid
graph TD;
  m-combobox --> m-option-listbox
style m-option-listbox fill:#008240,stroke:#333,stroke-width:4px
```
