DevactionUI.Pillbox (devaction_ui v0.2.3)

Copy Markdown View Source

A field of removable pills, for labels, e-mails, stacks: type and press Enter (or a comma) to add one, Backspace on an empty field removes the last, the × on a pill removes that one. Each pill is a hidden input named name[], so the form submits the list as it stands; the hook fires input on the box so phx-change hears every change. The browser owns the pills after mount (phx-update="ignore"): give it a new id to reset it from the server.

Text left in the field when it loses focus is added as a pill (Enter and the comma add it too). With every pill removed the form sends nothing for name[]: read the field with Map.get(params, "name", []) and take the absence as an empty list, or turn on empty_sentinel: the box then also carries a hidden name[]="" marker, so the field is always present, an emptied list arrives as [""] and clean_values/1 drops the marker. It is off by default so the values the hook reads stay only the pills. remove_label, added_label and removed_label take %{label}, which the server and the hook fill with the text of the pill; the last two are announced in a polite live region.

Summary

Functions

clean_values(values)

The values of a pillbox field as the form sent them, without the blank marker of empty_sentinel.

pillbox(assigns)

Functions

clean_values(values)

@spec clean_values(list() | nil) :: [String.t()]

The values of a pillbox field as the form sent them, without the blank marker of empty_sentinel.

pillbox(assigns)

Attributes

  • id (:string) (required)
  • name (:string) (required) - the field name; the values are sent as name[].
  • values (:list) - the pills of the first render only: the browser owns them after mount, so a new list needs a new id. Defaults to [].
  • label (:string) (required) - what the field is, for assistive technology.
  • placeholder (:string) - Defaults to nil.
  • remove_label (:string) (required) - names the × of each pill; %{label} is the pill's text, as in "Remove %{label}".
  • added_label (:string) - announced when a pill is added, as in "%{label} added". Defaults to nil.
  • removed_label (:string) - announced when a pill is removed, as in "%{label} removed". Defaults to nil.
  • disabled (:boolean) - Defaults to false.
  • empty_sentinel (:boolean) - adds a hidden name[]="" so an emptied list still reaches the server (as [""]); read it with clean_values/1. Defaults to false.
  • input_rest (:map) - attributes of the text field itself, such as aria-describedby, aria-invalid or required. Defaults to %{}.
  • class (:any) - Defaults to nil.
  • Global attributes are accepted.

Slots

  • remove_icon - replaces the typographic × that removes a pill.