Forms.autocomplete · Cinder UI

`Forms.autocomplete`

Progressive

Renders a filterable autocomplete input backed by a hidden form value.

This is intended for searching and selecting from a known set of options. Use select/1 when you want a trigger-driven listbox instead of a text input.

When to use it

Use autocomplete/1 when the person typing should search by label, but the form needs to submit a separate stable value through the hidden input.

Prefer combobox/1 for simpler label-in/label-out filtering where the typed text itself is the selected value and you do not need a separate hidden form field.

For server-backed search, keep the current query in LiveView assigns and update the option list on phx-change or phx-input. The component keeps its hidden value form-friendly while the visible input remains a normal text field that can participate in debounced LiveView events.

With FormField

<.autocomplete field={@form[:owner]}>
  <:option value="levi" label="Levi Buzolic" />
  <:option value="mira" label="Mira Chen" />
</.autocomplete>

With label

<.autocomplete field={@form[:owner]} label="Owner">
  <:option value="levi" label="Levi Buzolic" />
</.autocomplete>

With explicit errors

<.autocomplete field={@form[:owner]} label="Owner" errors={["is required"]}>
  <:option value="levi" label="Levi Buzolic" />
</.autocomplete>

Inside field composition

<.field>
  <:label><.label for={@form[:owner].id}>Owner</.label></:label>
  <.autocomplete field={@form[:owner]}>
    <:option value="levi" label="Levi Buzolic" />
  </.autocomplete>
  <:description>Assign a teammate to this project.</:description>
</.field>

Autocomplete

  <.autocomplete id="team-owner" name="owner" value="levi">
  <:option value="levi" label="Levi Buzolic" description="Engineering" />
  <:option value="mira" label="Mira Chen" description="Design" />
  <:option value="sam" label="Sam Hall" description="Operations" />
</.autocomplete>

Loading state

  <.autocomplete id="repo-search" name="repo" loading={true}>
  <:option value="cinder" label="cinder_ui" />
</.autocomplete>

LiveView server search

  <.form for={%{}} phx-change="search-owners">
  <.autocomplete
    id="owner-search"
    name="owner"
    value="mira"
    placeholder="Search teammates..."
    loading={false}
    phx-debounce="300"
    aria-label="Search owners"
  >
    <:option value="levi" label="Levi Buzolic" />
    <:option value="mira" label="Mira Chen" />
    <:empty>No teammates match the current query.</:empty>
  </.autocomplete>
</.form>

Attributes

Name	Type	Default	Values	Global Includes
`class`	`:string`	—	—	—
`content_class`	`:string`	—	—	—
`disabled`	`:boolean`	`false`	—	—
`errors`	`:list`	—	—	—
`field`	`{:struct, Phoenix.HTML.FormField}`	—	—	—
`id`	`:string`	—	—	—
`label`	`:string`	—	—	—
`loading`	`:boolean`	`false`	—	—
`loading_text`	`:string`	`"Loading..."`	—	—
`name`	`:string`	—	—	—
`placeholder`	`:string`	`"Search options..."`	—	—
`rest`	`:global`	—	—	`required` , `aria-label`
`value`	`:string`	—	—	—

Slots

Slot	Slot Attributes
`empty`	—
`option` Required	`value` (:string) Required `label` (:string) Required `description` (:string) `disabled` (:boolean)