04 · Forms — selection

Autocomplete

size sm/md/lg · term highlight · create new

A search field that filters a long list while the user types.

Typing and filtering

.heex
<.autocomplete id="ac01" open free_text value="mercad" class="max-w-[300px] [&_[data-part=autocomplete-control]]:animate-[lu-focusloop_6s_ease-in-out_infinite] [&_[data-part=autocomplete-input]]:animate-[lu-typeloop_6s_steps(6)_infinite] [&_[data-part=autocomplete-panel]]:animate-[lu-flin2_5s_ease-out_infinite] [&_[role=listbox]>button]:animate-[lu-hl_4s_infinite] [&_[role=listbox]>button:nth-child(2)]:[animation-delay:1.3s] [&_[role=listbox]>button:nth-child(3)]:[animation-delay:2.6s]" options={[%{label: "Mercadinho Bom Preço", value: "a", icon: "building"}, %{label: "Mercado São João", value: "b", icon: "building"}, %{label: "Mercado Central", value: "c", icon: "building"}]} />

size sm/md/lg

.heex
<div class="flex flex-wrap items-center gap-2.5">
  <div :for={size <- ~w(sm md lg)} class="w-[200px]">
    <.autocomplete id={"ac02-#{size}"} size={size} placeholder={"size=#{size}"} options={["Orbit Cloud", "Orbital Labs", "Orbis Systems"]} />
  </div>
</div>

Usage

<.autocomplete field={@form[:account]} search="search_accounts" />

Rules

  • Highlight the part that matched in 600.
  • Show metadata on the right (plan, MRR) to disambiguate.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

A text input with a list of suggestions under it. The person types, the list narrows (or the server searches) and choosing a suggestion sets the field. Behaviour lives in the LedgerUI.Autocomplete hook (priv/static/ledger_ui/hooks/autocomplete.js).

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

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

The choice is submitted through a hidden input named like the field; the visible input only shows the label. A bubbling input event fires from the hidden input, so a surrounding phx-change runs. With free_text the typed text is the value.

Without on_search the list filters itself on the client (ignoring case and accents). With it the hook pushes %{"id" => id, "query" => text} (after debounce ms and search_threshold characters) to target or the LiveView, shows loading_text until the reply and the server answers by re-rendering options. Options may carry :hint (a dimmed note at the right), :icon, :initials (an avatar, :tone "t1".."t5" picks its color, else taken from the label) and :disabled.

<.autocomplete>

Attr Type Default Values / notes
id :string nil
name :string nil
value :any nil
field {:struct, Phoenix.HTML.FormField} nil
label :string nil
label_hint :string nil Muted text beside the label (opcional).
help :string nil
errors :list []
options :list []
placeholder :string nil
disabled :boolean false
display_value :string nil
free_text :boolean false
on_search :string nil
debounce :integer 300
search_threshold :integer 0
target :any nil
open_on_focus :boolean false
clearable :boolean false
clear_label :string "Clear"
no_results :string "No results found"
loading_text :string "Searching…"
create :string nil
on_create :any nil
size :string "md" sm, md, lg
open :boolean false Renders the list open (static previews).
class :any nil

Any other HTML/phx attribute goes to the root element, including autofocus, form, required.

Slots:

  • <:option>
  • <:prefix>