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.

Add search-only terms with the option's :keywords attribute. Keywords are not rendered or announced and are only considered when the visible label does not match the current query.

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.

Autocomplete

  <.autocomplete id="team-owner" name="owner" value="levi">
  <:option
    value="levi"
    label="Levi Buzolic"
    description="Engineering"
    keywords={["backend", "Elixir"]}
  />
  <: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>

Autocomplete popup

  <div class="pb-48">
  <.autocomplete
    id="country-search"
    name="country"
    value="au"
    variant={:popup}
    placeholder="Search countries..."
    open={true}
  >
    <:option value="au" label="Australia" />
    <:option value="nz" label="New Zealand" />
    <:option value="us" label="United States" />
  </.autocomplete>
</div>

Grouped autocomplete

  <div class="pb-48">
  <.autocomplete
    id="timezone-search"
    name="timezone"
    placeholder="Search timezones..."
    open={true}
  >
    <:option value="nyc" label="(GMT-5) New York" group="Americas" />
    <:option value="lax" label="(GMT-8) Los Angeles" group="Americas" />
    <:option value="lon" label="(GMT+0) London" group="Europe" />
  </.autocomplete>
</div>

Custom autocomplete items

  <div class="pb-36">
  <.autocomplete
    id="framework-search"
    name="framework"
    open={true}
  >
    <:option value="next" label="Next.js">
      <span class="flex flex-col">
        <span class="font-medium">Next.js</span>
        <span class="text-muted-foreground text-xs">React framework</span>
      </span>
    </:option>
  </.autocomplete>
</div>

With FormField

Phoenix shim

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

With label

Phoenix shim

Owner

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

With explicit errors

Phoenix shim

Owner

is required

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

Inside field composition

Phoenix shim

Owner

Assign a teammate to this project.

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

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`	—	—	—
`open`	`:boolean`	`false`	—	—
`placeholder`	`:string`	`"Search options..."`	—	—
`rest`	`:global`	—	—	`required` , `aria-label`
`value`	`:string`	—	—	—
`variant`	`:atom`	`:input`	`:input` , `:popup`	—

Slots

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