Toddy.Iced.Widget.ComboBox (Toddy v0.3.0)

Copy Markdown View Source

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).

Summary

Types

option()
style()
t()

Functions

a11y(cb, a11y)

Sets accessibility annotations.

build(cb)

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

ellipsis(cb, ellipsis)

Sets the text ellipsis strategy.

font(cb, font)

Sets the font.

icon(cb, icon)

Sets the icon displayed inside the text input.

line_height(cb, line_height)

Sets the text line height.

menu_height(cb, menu_height)

Sets the maximum dropdown menu height in pixels.

menu_style(cb, menu_style)

Sets the dropdown menu style overrides.

new(id, options, opts \\ [])

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

on_close(cb, v)

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

on_open(cb, v)

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

on_option_hovered(cb, v)

Enables or disables option hover event emission.

padding(cb, padding)

Sets the internal padding.

placeholder(cb, placeholder)

Sets the placeholder text.

selected(cb, selected)

Sets the currently selected value.

shaping(cb, shaping)

Sets the text shaping strategy.

size(cb, size)

Sets the text size in pixels.

style(cb, style)

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

width(cb, width)

Sets the combo box width.

with_options(cb, opts)

Applies keyword options to an existing combo box struct.

Types

option()

@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()

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

t()

@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
}

Functions

a11y(cb, a11y)

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

Sets accessibility annotations.

build(cb)

@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(cb, ellipsis)

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

Sets the text ellipsis strategy.

font(cb, font)

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

Sets the font.

icon(cb, icon)

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

Sets the icon displayed inside the text input.

line_height(cb, line_height)

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

Sets the text line height.

new(id, options, opts \\ [])

@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(cb, v)

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

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

on_open(cb, v)

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

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

on_option_hovered(cb, v)

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

Enables or disables option hover event emission.

padding(cb, padding)

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

Sets the internal padding.

placeholder(cb, placeholder)

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

Sets the placeholder text.

selected(cb, selected)

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

Sets the currently selected value.

shaping(cb, shaping)

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

Sets the text shaping strategy.

size(cb, size)

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

Sets the text size in pixels.

style(cb, style)

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

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

width(cb, width)

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

Sets the combo box width.

with_options(cb, opts)

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

Applies keyword options to an existing combo box struct.