# `Toddy.Iced.Widget.ComboBox`
[🔗](https://github.com/toddy-ui/toddy-elixir/blob/v0.3.0/lib/toddy/iced/widget/combo_box.ex#L1)

Combo box -- searchable dropdown with free-form text input.

The renderer manages an internal `combo_box::State` cache keyed by node ID.
Options changes trigger a state rebuild.

## Props

- `options` (list of strings) -- the available choices.
- `selected` (string | nil) -- the currently selected value.
- `placeholder` (string) -- placeholder text.
- `width` (length) -- widget width. Default: fill. See `Toddy.Iced.Length`.
- `padding` (number | map) -- internal padding. See `Toddy.Iced.Padding`.
- `size` (number) -- text size in pixels.
- `font` (string | map) -- font specification. See `Toddy.Iced.Font`.
- `line_height` (number | map) -- text line height.
- `menu_height` (number) -- maximum height of the dropdown menu in pixels.
- `icon` (map) -- display an icon inside the text input. Same format as
  `Toddy.Iced.Widget.TextInput` icon prop.
- `on_option_hovered` (boolean) -- when true, emits `%Widget{type: :option_hovered, id: id, value: value}`
  when hovering over a dropdown option. Default: false.
- `shaping` -- text shaping strategy. See `Toddy.Iced.Shaping`.
- `ellipsis` (string) -- text ellipsis strategy: `"none"`, `"start"`, `"middle"`, or `"end"`.
  Default: `"end"`.
- `menu_style` (map) -- inline style for the dropdown menu. Map with optional keys:
  `background`, `text_color`, `selected_text_color`, `selected_background`, `border`, `shadow`.
- `style` -- named preset atom (`:default`) or `StyleMap.t()` for custom styling.
  See `Toddy.Iced.StyleMap`.
- `a11y` (map) -- accessibility overrides. See `Toddy.Iced.A11y`.

## Events

- `%Widget{type: :select, id: id, value: value}` -- emitted when an option is selected.
- `%Widget{type: :input, id: id, value: value}` -- emitted on every text input change (for filtering).
- `%Widget{type: :option_hovered, id: id, value: value}` -- emitted on hover (requires `on_option_hovered` prop).
- `%Widget{type: :open, id: id}` -- emitted when the dropdown menu is opened (requires `on_open: true`).
- `%Widget{type: :close, id: id}` -- emitted when the dropdown menu is closed (requires `on_close: true`).

# `option`

```elixir
@type option() ::
  {:selected, String.t()}
  | {:placeholder, String.t()}
  | {:width, Toddy.Iced.Length.t()}
  | {:padding, Toddy.Iced.Padding.t()}
  | {:size, number()}
  | {:font, Toddy.Iced.Font.t()}
  | {:line_height, number() | map()}
  | {:menu_height, number()}
  | {:icon, map()}
  | {:on_option_hovered, boolean()}
  | {:on_open, boolean()}
  | {:on_close, boolean()}
  | {:shaping, Toddy.Iced.Shaping.t()}
  | {:ellipsis, String.t()}
  | {:menu_style, map()}
  | {:style, style()}
  | {:a11y, Toddy.Iced.A11y.t()}
```

# `style`

```elixir
@type style() :: :default | Toddy.Iced.StyleMap.t()
```

# `t`

```elixir
@type t() :: %Toddy.Iced.Widget.ComboBox{
  a11y: Toddy.Iced.A11y.t() | nil,
  ellipsis: String.t() | nil,
  font: Toddy.Iced.Font.t() | nil,
  icon: map() | nil,
  id: String.t(),
  line_height: number() | map() | nil,
  menu_height: number() | nil,
  menu_style: map() | nil,
  on_close: boolean() | nil,
  on_open: boolean() | nil,
  on_option_hovered: boolean() | nil,
  options: [String.t()],
  padding: Toddy.Iced.Padding.t() | nil,
  placeholder: String.t() | nil,
  selected: String.t() | nil,
  shaping: Toddy.Iced.Shaping.t() | nil,
  size: number() | nil,
  style: style() | nil,
  width: Toddy.Iced.Length.t() | nil
}
```

# `a11y`

```elixir
@spec a11y(combo_box :: t(), a11y :: Toddy.Iced.A11y.t()) :: t()
```

Sets accessibility annotations.

# `build`

```elixir
@spec build(combo_box :: t()) :: Toddy.Iced.ui_node()
```

Converts this combo box struct to a `ui_node()` map via the `Toddy.Iced.Widget` protocol.

# `ellipsis`

```elixir
@spec ellipsis(combo_box :: t(), ellipsis :: String.t()) :: t()
```

Sets the text ellipsis strategy.

# `font`

```elixir
@spec font(combo_box :: t(), font :: Toddy.Iced.Font.t()) :: t()
```

Sets the font.

# `icon`

```elixir
@spec icon(combo_box :: t(), icon :: map()) :: t()
```

Sets the icon displayed inside the text input.

# `line_height`

```elixir
@spec line_height(combo_box :: t(), line_height :: number() | map()) :: t()
```

Sets the text line height.

# `menu_height`

```elixir
@spec menu_height(combo_box :: t(), menu_height :: number()) :: t()
```

Sets the maximum dropdown menu height in pixels.

# `menu_style`

```elixir
@spec menu_style(combo_box :: t(), menu_style :: map()) :: t()
```

Sets the dropdown menu style overrides.

# `new`

```elixir
@spec new(id :: String.t(), options :: [String.t()], opts :: [option()]) :: t()
```

Creates a new combo box struct with the given options and optional keyword opts.

# `on_close`

```elixir
@spec on_close(combo_box :: t(), on_close :: boolean()) :: t()
```

Enables or disables the close event when the dropdown menu closes.

# `on_open`

```elixir
@spec on_open(combo_box :: t(), on_open :: boolean()) :: t()
```

Enables or disables the open event when the dropdown menu opens.

# `on_option_hovered`

```elixir
@spec on_option_hovered(combo_box :: t(), on_option_hovered :: boolean()) :: t()
```

Enables or disables option hover event emission.

# `padding`

```elixir
@spec padding(combo_box :: t(), padding :: Toddy.Iced.Padding.t()) :: t()
```

Sets the internal padding.

# `placeholder`

```elixir
@spec placeholder(combo_box :: t(), placeholder :: String.t()) :: t()
```

Sets the placeholder text.

# `selected`

```elixir
@spec selected(combo_box :: t(), selected :: String.t()) :: t()
```

Sets the currently selected value.

# `shaping`

```elixir
@spec shaping(combo_box :: t(), shaping :: Toddy.Iced.Shaping.t()) :: t()
```

Sets the text shaping strategy.

# `size`

```elixir
@spec size(combo_box :: t(), size :: number()) :: t()
```

Sets the text size in pixels.

# `style`

```elixir
@spec style(combo_box :: t(), style :: style()) :: t()
```

Sets the combo box style. Accepts `:default` or a `StyleMap`.

# `width`

```elixir
@spec width(combo_box :: t(), width :: Toddy.Iced.Length.t()) :: t()
```

Sets the combo box width.

# `with_options`

```elixir
@spec with_options(combo_box :: t(), opts :: [option()]) :: t()
```

Applies keyword options to an existing combo box struct.

---

*Consult [api-reference.md](api-reference.md) for complete listing*