LineaUI.Components.Autocomplete (linea_ui v0.3.0)

Copy Markdown View Source

A text input with a list of suggestions under it, in LineOne's Tom Select look: the person types, the list narrows (or the server searches), and choosing a suggestion sets the field.

<.autocomplete field={@form[:customer_id]} label="Customer" options={@customers}
               on_search="search_customers" placeholder="Pick a customer" clearable />

<.autocomplete field={@form[:product_id]} options={@products} on_search="search_products"
               no_results="Nothing for \"%{query}\"" open_on_focus target={@myself}>
  <:option :let={product}>{product.label} <small>{product.data.sku}</small></:option>
</.autocomplete>

<.autocomplete field={@form[:city]} options={["Salvador", "Santos", "São Paulo"]} free_text />

Options are strings, {label, value} tuples or maps with :label and :value (other keys reach the :option slot as option.data), as in LineaUI.Components.Select.Options.

The choice is submitted through a hidden input named like the field; the visible input only shows the chosen option's label. A bubbling input event fires from the hidden input when the value changes, so a surrounding phx-change runs. Leaving the input with text that is not an option puts the chosen label back; leaving it empty clears the value.

With free_text the typed text itself is the value (the suggestions only complete it): every keystroke updates the hidden input, and choosing a suggestion writes its value.

Without on_search the list filters itself on the client (ignoring case and accents). With it, the hook pushes the query to the server, shows loading_text until the reply, and the server answers by re-rendering options.

The behavior lives in the LineaUI.Autocomplete hook, so the field needs a stable id (it gets one from field or name).

Summary

Functions

autocomplete(assigns)

Renders the autocomplete.

Functions

autocomplete(assigns)

Renders the autocomplete.

Events: with on_search, typing pushes on_search with %{"id" => id, "query" => text} (after debounce ms, once the query has search_threshold characters) to target or to the LiveView/LiveComponent the field is in. Choosing, clearing or (with free_text) typing fires the form's phx-change with the field's value.

Attributes

  • id (:string) - Defaults to the field id, then name, then a generated one.
  • name (:string) - Defaults to the field name.
  • value (:any) - The chosen value. Defaults to the field value.
  • field (Phoenix.HTML.FormField) - A form field: fills id, name, value and errors. Defaults to nil.
  • label (:string) - Defaults to nil.
  • help (:string) - Defaults to nil.
  • errors (:list) - Defaults to [].
  • options (:list) - The suggestions, see the module doc. Defaults to [].
  • placeholder (:string) - Defaults to nil.
  • disabled (:boolean) - Defaults to false.
  • display_value (:string) - The text shown for value when it is not among options (a chosen customer the current search no longer returns). Defaults to nil.
  • free_text (:boolean) - The typed text is the value; the suggestions only complete it. Defaults to false.
  • on_search (:string) - The event pushed with the query: the server searches. Defaults to nil.
  • debounce (:integer) - Milliseconds between the last keystroke and the push. Defaults to 300.
  • search_threshold (:integer) - How many characters before searching. Defaults to 0.
  • target (:any) - Defaults to nil.
  • open_on_focus (:boolean) - Show the suggestions as soon as the input has focus. Defaults to false.
  • clearable (:boolean) - A button that empties the field. Defaults to false.
  • clear_label (:string) - Defaults to "Clear".
  • no_results (:string) - Shown when nothing matches; %{query} is replaced by what was typed. Defaults to "No results found".
  • loading_text (:string) - Shown while the server searches. Defaults to "Searching…".
  • size (:string) - Defaults to "md". Must be one of "sm", "md", or "lg".
  • class (:any) - Defaults to nil.
  • Global attributes are accepted. Goes to the visible input (aria-label...), except phx-debounce/phx-throttle, which go to the hidden one. Supports all globals plus: ["autofocus", "form", "required"].

Slots

  • option - How a suggestion shows in the list; gets the option map (label, value, data).
  • prefix - An icon inside the control, before the text.