DevactionUI.Combobox (devaction_ui v0.2.3)

Copy Markdown View Source

A select with a search box: the button shows the choice, the panel has a field that filters the list while you type (ignoring case and accents), ↑ ↓ move, Enter chooses, Esc closes, and an empty result says so. ↓ or ↑ on the button opens it. The value goes in a hidden input named name, and the hook fires input on it so phx-change hears it. Options are %{value: ..., label: ..., hint: ...}; hint is a small mono text at the right.

Written as the ARIA combobox pattern: the field keeps focus and points at the active option with aria-activedescendant. The button is named by label and by the chosen text together (aria-labelledby), so the choice is read out.

The options are read live: when options changes (a dependent select, a search on the server) the list follows, and the filter is applied again. What the hook sets on the page itself (open, active, filtered) is kept across a patch; the chosen value is the caller's, as in any LiveView field, so a form that re-renders should hold value (with phx-change).

label is the accessible name and is hidden; show_label draws it above the field (13px, weight 500), as the other fields of a form, and help is a line of explanation under the field. Both are read with the field (aria-labelledby, aria-describedby), together with the error.

disabled locks it (and keeps the value out of the form), required marks it for assistive technology (a hidden input cannot be validated by the browser, so check it on the server) and error is the message that goes under it and marks it invalid. With clear_label there is a button that empties the choice. Icons are slots: chevron_icon (a ⌄ when there is none), search_icon, clear_icon, and option_marker, drawn before the label of each option (a color swatch, an avatar) and given the option.

Summary

Functions

combobox(assigns)

@spec combobox(map()) :: Phoenix.LiveView.Rendered.t()

Attributes

  • id (:string) (required)
  • name (:string) (required)
  • options (:list) (required) - %{value, label, hint} each (hint is optional); read live, so they may change.
  • value (:string) - Defaults to nil.
  • label (:string) (required) - what is being chosen, for assistive technology.
  • placeholder (:string) (required) - shown on the button when nothing is chosen.
  • search_placeholder (:string) (required)
  • empty (:string) (required) - shown when the search finds nothing.
  • disabled (:boolean) - Defaults to false.
  • required (:boolean) - Defaults to false.
  • show_label (:boolean) - draws label above the field instead of leaving it for assistive technology only. Defaults to false.
  • help (:string) - a line of explanation under the field. Defaults to nil.
  • error (:string) - the message under the field; also marks it invalid. Defaults to nil.
  • clear_label (:string) - the name of the button that empties the choice; none when nil. Defaults to nil.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • chevron_icon - the arrow at the end of the button; turns over when open.
  • search_icon - the magnifier in the search field.
  • clear_icon - the icon of the clear button.
  • option_marker - drawn before the label of each option; gets the option.