Dropdown

A material dropdown menu for choosing one value from a list of options. Options are built with dropdown_option.

Example

dropdown(
  label: "Fruit",
  value: "apple",
  options: [
    dropdown_option(key: "apple", text: "Apple"),
    dropdown_option(key: "banana", text: "Banana"),
    dropdown_option(key: "cherry", text: "Cherry")
  ],
  on_select: ->(event) { page.update(status, value: "Picked #{event.control.value}") }
)

Common properties

• value — the selected option key
• options — an array of dropdown_option
• label
• hint_text
• helper_text
• error_text
• filled
• bgcolor
• border / border_color / border_radius
• editable — allow typing into the field
• enable_filter / enable_search
• leading_icon / trailing_icon

Use on_select when an option is selected. Editable dropdowns also expose on_text_change, on_focus, and on_blur; the current Dropdown API does not define an on_change event.

Options

dropdown_option(key: "us", text: "United States", leading_icon: "flag")

• key — the value stored on the dropdown
• text — the visible label
• content — a custom control instead of text
• leading_icon / trailing_icon
• disabled

Usage

Read the choice from control.value:

field = dropdown(
  label: "Size",
  options: [dropdown_option(key: "s", text: "Small"), dropdown_option(key: "l", text: "Large")]
)
# later:
field.value # => "s"

Complete API

Helpers

• dropdown(options = ..., **props)

Accepted properties

• align — Alignment of the control within its parent.
• animate_align — Animates alignment changes.
• animate_margin — Animates margin changes.
• animate_offset — Animates offset changes.
• animate_opacity — Animates opacity changes.
• animate_position — Animates position changes.
• animate_rotation — Animates rotation changes.
• animate_scale — Animates scale changes.
• animate_size — Animates size changes.
• aspect_ratio — Width-to-height ratio to maintain.
• autofocus — Requests focus when first shown.
• badge — Badge drawn on the corner of the control.
• bgcolor — Background color.
• border — Border definition.
• border_color — Border color.
• border_radius — Corner radius.
• border_width — Border thickness.
• bottom — Bottom offset when positioned inside a stack.
• capitalization — Sets the capitalization property.
• col — Responsive column span (1-12) per breakpoint.
• color — Foreground color.
• content_padding — Content padding.
• data — Arbitrary value you can attach to the control and read back in handlers.
• dense — Sets the dense property.
• disabled — Disables interaction when true.
• editable — Sets the editable property.
• elevation — Shadow depth (z-height).
• enable_filter — Sets the enable filter property.
• enable_search — Sets the enable search property.
• error_style — Error style.
• error_text — Error message shown below the field; also marks it invalid.
• expand — Fills the available space along the parent's main axis when true.
• expand_loose — Like expand, but only grows up to the child's natural size.
• expanded_insets — Sets the expanded insets property.
• fill_color — Fill color.
• filled — Sets the filled property.
• focused_border_color — Focused border color.
• focused_border_width — Focused border width.
• height — Fixed height in logical pixels.
• helper_style — Helper style.
• helper_text — Helper text shown below the field.
• hint_style — Hint style.
• hint_text — Placeholder shown when the field is empty.
• hover_color — Color shown while hovered.
• input_filter — Sets the input filter property.
• key — Stable identity used to preserve state across rebuilds.
• label — Text label shown for the control.
• label_style — Label style.
• leading_icon — Leading icon.
• left — Left offset when positioned inside a stack.
• margin — Outer spacing around the control.
• menu_height — Menu height.
• menu_style — Menu style.
• menu_width — Menu width.
• offset — Translation offset applied to the control.
• opacity — Opacity from 0.0 (transparent) to 1.0 (opaque).
• options — The selectable options (built with the control's option helper).
• right — Right offset when positioned inside a stack.
• rotate — Rotation applied to the control.
• rtl — Renders right-to-left when true.
• scale — Scale transform applied to the control.
• selected_suffix — Sets the selected suffix property.
• selected_trailing_icon — Selected trailing icon.
• size_change_interval — Throttle interval for on_size_change, in ms.
• text — Text content of the control.
• text_align — Sets the text align property.
• text_size — Sets the text size property.
• text_style — Text style.
• tooltip — Text shown on hover/long-press.
• top — Top offset when positioned inside a stack.
• trailing_icon — Trailing icon.
• value — The control's current value.
• visible — Hides the control when false.
• width — Fixed width in logical pixels.

Events

• on_animation_end — Fired when an animation completes.
• on_blur — Fired when the control loses focus.
• on_focus — Fired when the control gains focus.
• on_select — Fired when a selection is made.
• on_size_change — Fired when the control's size changes.
• on_text_change — Fired on text change.

Wire reference

• Family: materials
• Widget type: dropdown