AuroraUI.Components.Selection (Aurora UI v0.1.1)

View Source

Selection family — a styled native select/1 and an accessible, hook-enhanced combobox/1 autocomplete.

select/1 is the reliable baseline: a real <select> styled with tokens and a custom chevron, with label association, prompt, sizes, and disabled/invalid states. It needs no JavaScript.

combobox/1 progressively enhances a text input into an ARIA combobox with a listbox popup. The HEEx renders the full, correct ARIA skeleton; the AuroraCombobox hook layers on keyboard and pointer behavior.

Combobox DOM & hook contract

The phx-hook="AuroraCombobox" lives on the <input role="combobox">, keyed to a stable id. From that id the component derives deterministic ids so ARIA relationships survive LiveView patches:

  • input: #{id}
  • listbox: #{id}-listbox (referenced by aria-controls)
  • option n: #{id}-option-#{n}

The input carries aria-expanded, aria-controls, aria-autocomplete="list", and aria-busy while loading. Each <li role="option"> carries a deterministic id, data-value, aria-selected, and aria-disabled.

The hook is responsible for: keyboard interaction (ArrowUp/ArrowDown, Enter, Escape, Home/End, printable-character typeahead), pointer selection, click-away dismissal, marking the active option with data-aui-active, and reflecting the active option into aria-activedescendant on the input. It respects prefers-reduced-motion and cleans up on destroyed().

Filtering and selection stay server-driven. The AuroraCombobox hook pushes LiveView server events (pushEventTo on the component root) that you handle in handle_event/3:

  • "aui:combobox:filter" — %{"id" => id, "query" => query} (input changed)
  • "aui:combobox:select" — %{"id" => id, "value" => value, "label" => label}
  • "aui:combobox:open" / "aui:combobox:close" — %{"id" => id}
  • "aui:combobox:clear" — %{"id" => id}

By default the hook filters client-side; add data-aui-remote to defer filtering to the server (it then pushes only …:filter and re-reads options after the patch). Options come from the options attribute (convenience) or one or more <:option> slots (custom markup); when both are empty and loading is false a no-results row is shown.

Summary

Functions

combobox(assigns)

An accessible autocomplete combobox. The server owns the option list (filter it in a phx-change handler); the AuroraCombobox hook owns keyboard, pointer, and active-descendant behavior. See the module doc for the full contract.

select(assigns)

A styled native <select>. Prefer it over combobox/1 whenever the full list is short and known — it is the most robust, zero-JS option.

Functions

combobox(assigns)

An accessible autocomplete combobox. The server owns the option list (filter it in a phx-change handler); the AuroraCombobox hook owns keyboard, pointer, and active-descendant behavior. See the module doc for the full contract.

Use it when the list is long, remote, or benefits from type-to-filter; for a short static list, select/1 is simpler and needs no JS.

Examples

<.combobox id="fruit" name="fruit" label="Fruit" value={@query}
  selected={@selected} open={@open} loading={@loading} phx-change="filter"
  options={@matches} />

Attributes

  • id (:string) - Defaults to nil.
  • name (:string) - form field name for the typed/selected value. Defaults to nil.
  • value (:string) - current text value of the input. Defaults to "".
  • selected (:string) - committed option value, for aria-selected. Defaults to nil.
  • label (:string) - Defaults to nil.
  • placeholder (:string) - Defaults to nil.
  • options (:list) - {label, value} tuples or maps; used when no <:option> slots are given. Defaults to [].
  • disabled (:boolean) - Defaults to false.
  • invalid (:boolean) - Defaults to false.
  • loading (:boolean) - sets aria-busy and shows a spinner. Defaults to false.
  • required (:boolean) - Defaults to false.
  • open (:boolean) - server-controlled expanded state. Defaults to false.
  • clearable (:boolean) - render the clear button. Defaults to true.
  • empty_label (:string) - shown when there are no options. Defaults to "No results".
  • Global attributes are accepted. Supports all globals plus: ["phx-change", "phx-focus", "phx-blur", "phx-debounce", "autocomplete", "maxlength"].

Slots

  • option - custom option markup; overrides options when present. Accepts attributes:
    • value (:string)
    • disabled (:boolean)
    • selected (:boolean)

select(assigns)

A styled native <select>. Prefer it over combobox/1 whenever the full list is short and known — it is the most robust, zero-JS option.

Examples

<.select label="Country" name="country" value={@country} prompt="Choose…"
  options={[{"United States", "us"}, {"United Kingdom", "uk"}]} />

Attributes

  • id (:string) - Defaults to nil.
  • name (:string) - Defaults to nil.
  • label (:string) - visible label, associated via for/id. Defaults to nil.
  • value (:string) - the selected option value. Defaults to nil.
  • options (:list) - {label, value} tuples or maps with :label/:value/:disabled. Defaults to [].
  • prompt (:string) - disabled placeholder option shown first. Defaults to nil.
  • disabled (:boolean) - Defaults to false.
  • invalid (:boolean) - Defaults to false.
  • size (:string) - Defaults to "md". Must be one of "sm", "md", or "lg".
  • Global attributes are accepted. Supports all globals plus: ["form", "required", "multiple", "phx-change", "phx-blur", "phx-focus", "autocomplete"].

Slots

  • description - helper text wired as aria-describedby.