04 · Forms — selection

Select

variant outline/filled · size · shape · multiple with overflow count/wrap · search control/panel/none

Pick one option from a short list, with an input-shaped trigger.

Opening and choosing

Matriz · Feira de Santana
.heex
<.select id="sel01" open icon="building" value="matriz" class="w-full! [&_[data-part=select-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={[{"Matriz · Feira de Santana", "matriz"}, {"Filial Serrinha", "serrinha"}, {"Filial Alagoinhas", "alagoinhas"}]} />

variant outline/filled × size sm/md/lg

sm md lg outline
filled
.heex
<div class="grid grid-cols-[80px_repeat(3,minmax(0,1fr))] items-center gap-x-3 gap-y-2.5">
  <span></span>
  <span class="text-center font-mono text-xs text-muted">sm</span>
  <span class="text-center font-mono text-xs text-muted">md</span>
  <span class="text-center font-mono text-xs text-muted">lg</span>
  <%= for variant <- ~w(outline filled) do %>
    <span class="font-mono text-xs text-muted">{variant}</span>
    <div :for={size <- ~w(sm md lg)} class="flex min-w-0 justify-center">
      <.select id={"sel02-#{variant}-#{size}"} variant={variant} size={size} icon="building" value="matriz" options={[{"Matriz · Feira de Santana", "matriz"}]} />
    </div>
  <% end %>
</div>

shape · overflow count/wrap · search control/panel/none

.heex
<div class="flex flex-wrap items-center gap-2.5">
  <.select id="sel03-pill" shape="pill" icon="building" value="matriz" options={[{"Matriz · Feira de Santana", "matriz"}]} />
  <.pillbox removable={false} chevron={false} id="sel03-multi" value={["matriz", "serrinha", "alagoinhas", "serra"]} options={[{"Matriz", "matriz"}, {"Serrinha", "serrinha"}, {"Alagoinhas", "alagoinhas"}, {"Serra", "serra"}]} />
  <.autocomplete id="sel03-search" class="max-w-[220px]" placeholder="Buscar filial…" options={["Matriz", "Serrinha"]} />
</div>

Open

Pro
Scale
Starter
Enterprise Em breve
.heex
<.listbox value="Pro" label="Plano" class="w-[280px]" options={["Pro", "Scale", "Starter", {"", [%{label: "Enterprise", hint: "Em breve", disabled: true}]}]} />

API values that complete the parity

shape=rounded
.heex
<div class="grid grid-cols-3 gap-3.5">
  <div class="flex flex-col items-start gap-1.5"><.select id="sel05-rounded" icon="building" value="matriz" options={[{"Matriz · Feira de Santana", "matriz"}]} /><span class="font-mono text-[11px] text-muted">shape=rounded</span></div>
</div>

Try it: search in the panel in multiple

Estados atendidos (multiple, busca no painel)
Um estado (search=&quot;panel&quot;)
.heex
<% states = [{"Acre", "AC"}, {"Alagoas", "AL"}, {"Amapá", "AP"}, {"Amazonas", "AM"}, {"Bahia", "BA"}, {"Ceará", "CE"}, {"Distrito Federal", "DF"}, {"Espírito Santo", "ES"}, {"Goiás", "GO"}, {"Maranhão", "MA"}, {"Mato Grosso", "MT"}, {"Minas Gerais", "MG"}, {"Pará", "PA"}, {"Paraná", "PR"}, {"Pernambuco", "PE"}, {"Rio de Janeiro", "RJ"}, {"Santa Catarina", "SC"}, {"São Paulo", "SP"}] %>
<div class="flex max-w-[420px] flex-col gap-4">
  <.select id="sel-multi-search" class="w-full" name="states" label="Estados atendidos (multiple, busca no painel)" options={states} multiple removable search="panel" search_placeholder="Buscar estado…" placeholder="Escolha os estados" />
  <.select id="sel-single-search" class="w-full" name="state" label="Um estado (search=&quot;panel&quot;)" options={states} search="panel" search_placeholder="Buscar estado…" placeholder="Escolha um estado" />
</div>

Usage

<.select field={@form[:plan]} options={["Pro", "Scale", "Starter"]} />

Rules

  • Up to ~10 options; above that use Autocomplete.
  • The chosen option in 500 with a teal check on the right.

API reference

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

Select: the styled native <select> (native) and a searchable listbox driven by the LedgerUI.Select hook (priv/static/ledger_ui/hooks/select.js).

<.select native label="Type" options={~w(Wedding Birthday Other)} />
<.select field={@form[:plan]} options={["Pro", "Scale", "Starter"]} />
<.select field={@form[:states]} options={@states} multiple removable clearable />
<.select field={@form[:author]} options={@authors} on_search="search_authors" target={@myself}>
  <:option :let={author}>{author.label} · {author.data.job}</:option>
</.select>

Options are strings, {label, value} tuples, maps or {group, options} (see LedgerUI.Components.Select.Options).

The listbox submits through a hidden <select> named like the field (name[] when multiple) and fires a bubbling input event when the choice changes, so a surrounding phx-change runs. Opening, closing, keyboard and filtering never leave the browser; a value sent by the server wins over the one in the browser.

Width: the root is w-[260px] by default. In a form or a grid pass class="w-full" so the control and the panel take the whole column (like the inputs next to it):

<.select field={@form[:status]} options={@statuses} multiple class="w-full" />

Search: search is "auto" by default: the filter box is in the control for a single select and at the top of the panel (focused when it opens) when multiple, where the control is taken by the chips and the +N. "control", "panel" and "none" are kept as given.

Height: with overflow="count" (default) a multiple control has the height of an input of the same size with 0, 1 or many chips; overflow="wrap" grows with the chips.

on_search pushes %{"id" => id, "query" => text} (after debounce ms) and on_load_more pushes %{"id" => id, "query" => text, "offset" => n} to target or the LiveView.

<.select>

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
help :string nil
errors :list []
options :list []
prompt :string nil
placeholder :string nil
multiple :boolean false
disabled :boolean false
native :boolean false
variant :string "outline" outline, filled
size :string "md" sm, md, lg
shape :string "rounded" rounded, pill
inline :boolean false
icon :string nil An icon before the text.
removable :boolean false
clearable :boolean false
clear_label :string "Clear"
remove_label :string "Remove"
create :boolean false
create_label :string "Add"
create_hint :string nil
persist :boolean true
restore_on_backspace :boolean false
max :integer nil
overflow :string "count" count, wrap
footer :boolean false
footer_count :string "%{count} of %{total}"
footer_hint :string "Esc to close"
more_label :string "more"
no_results :string "No results found"
search :string "auto" auto, control, panel, none - Where the filter box is: auto is panel when multiple and control otherwise.
search_placeholder :string "Search…"
panel_min_width :string nil
panel_class :any nil
on_search :string nil
debounce :integer 300
target :any nil
on_load_more :string nil
has_more :boolean false
loading_label :string "Loading…"
open :boolean false Renders the list open (static previews).
class :any nil

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

Slots:

  • <:below>
  • <:item>
  • <:label_aside>
  • <:option>
  • <:suffix>

<.listbox>

A static list of choices (the open panel of a select, without the trigger): the chosen row is bold with a check, a disabled option is dimmed and a hint goes at the right.

<.listbox value="pro" class="w-[280px]" options={[
  {"Pro", "pro"}, "Scale", "Starter",
  {"", [%{label: "Enterprise", hint: "Soon", disabled: true}]}]} />
Attr Type Default Values / notes
id :string nil
options (required) :list Options as in select/1; a {label, [options]} group is set apart by a divider (its label is drawn when not empty).
value :any nil The chosen value (or list of values): its row is bold with a check.
label :string nil Accessible name of the list.
class :any nil Layout classes of the panel (w-[280px]).

Slots:

  • <:option> - Content of a row (receives the normalized option).