A type-to-search input that filters and selects from a list of options, with client-side and server-side search support, keyboard navigation, and full Phoenix form integration.

The autocomplete component provides a combobox-style text input where users type to filter a dropdown of options. It is optimized for search-driven selection workflows of any dataset size, and offers customizable search modes, debounced server-side search, animated transitions, grouped options with nesting, custom option rendering, and rich empty-state handling.

Usage

Basic usage with a list of options:

<.autocomplete
  name="country"
  options={[{"United States", "us"}, {"Canada", "ca"}]}
  placeholder="Search countries..."
/>

The component follows the same options API as Phoenix.HTML.Form.options_for_select/2, supporting multiple formats:

# List of strings
<.autocomplete name="fruit" options={["Apple", "Banana", "Cherry"]} />

# List of tuples (label, value)
<.autocomplete name="country" options={[{"United States", "us"}, {"Canada", "ca"}]} />

# Keyword list
<.autocomplete name="lang" options={[English: "en", Spanish: "es", French: "fr"]} />

# Keyword list with key/value/disabled
<.autocomplete
  name="role"
  options={[
    [key: "Admin", value: "admin"],
    [key: "User", value: "user", disabled: true],
    [key: "Guest", value: "guest"]
  ]}
/>

# Grouped options
<.autocomplete
  name="city"
  options={[
    {"North America", [{"New York", "nyc"}, {"Toronto", "tor"}]},
    {"Europe", [{"London", "lon"}, {"Paris", "par"}]}
  ]}
/>

# Multi-level nested groups (flattened with visual indentation)
<.autocomplete
  name="city"
  options={[
    {"Europe", [
      {"France", [{"Paris", 1}, {"Lyon", 2}]},
      {"Italy", [{"Rome", 3}, {"Milan", 4}]}
    ]},
    {"Asia", [
      {"China", [{"Beijing", 5}, {"Shanghai", 6}]}
    ]}
  ]}
/>

A full-featured example combining labels, description, help text, and placeholder:

<.autocomplete
  name="deployment"
  label="Deployment Platform"
  sublabel="Optional"
  description="This will determine your deployment configuration"
  help_text="Choose from our supported platforms"
  placeholder="Select platform..."
  options={["Fly.io", "Railway", "Heroku", "Render", "AWS"]}
/>

Size Variants

The autocomplete component offers five size variants to fit different interface densities:

<.autocomplete name="xs" size="xs" options={@options} placeholder="Extra small" />
<.autocomplete name="sm" size="sm" options={@options} placeholder="Small" />
<.autocomplete name="md" size="md" options={@options} placeholder="Medium (default)" />
<.autocomplete name="lg" size="lg" options={@options} placeholder="Large" />
<.autocomplete name="xl" size="xl" options={@options} placeholder="Extra large" />

Each size variant adjusts height, padding, font size, icon dimensions, and affix sizing proportionally.

Labels and Descriptions

Provide context and guidance with comprehensive labeling:

# Basic label
<.autocomplete name="language" label="Language" options={@languages} />

# Label with sublabel
<.autocomplete name="language" label="Language" sublabel="Required" options={@languages} />

# Label with description
<.autocomplete
  name="language"
  label="Language"
  description="Choose the primary language for your project"
  options={@languages}
/>

# Complete example with help text
<.autocomplete
  name="language"
  label="Language"
  sublabel="Optional"
  description="Used for localization purposes"
  help_text="You can change this later in settings"
  placeholder="Search languages..."
  options={@languages}
/>

Form Integration

The autocomplete component integrates with Phoenix forms in two ways: using the field attribute for full form integration or using the name attribute for standalone inputs.

Using with Phoenix Forms (Recommended)

Use the field attribute to bind the autocomplete to a form field:

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.autocomplete
    field={f[:assigned_to_id]}
    label="Assigned To"
    options={@users}
  />
</.form>

Using the field attribute provides:

• Automatic value handling from form data
• Error handling and validation messages
• Form submission with correct field names
• Integration with changesets
• ID generation for accessibility

Complete example with a changeset implementation:

defmodule MyApp.Task do
  use Ecto.Schema
  import Ecto.Changeset

  schema "tasks" do
    field :title, :string
    belongs_to :assigned_to, MyApp.User
    timestamps()
  end

  def changeset(task, attrs) do
    task
    |> cast(attrs, [:assigned_to_id, :title])
    |> validate_required([:assigned_to_id])
  end
end

# In your LiveView
def mount(_params, _session, socket) do
  users = MyApp.Accounts.list_active_users() |> Enum.map(&{&1.name, &1.id})
  changeset = Task.changeset(%Task{}, %{})

  {:ok, assign(socket, users: users, form: to_form(changeset))}
end

def render(assigns) do
  ~H"""
  <.form :let={f} for={@form} phx-change="validate">
    <.autocomplete
      field={f[:assigned_to_id]}
      options={@users}
      label="Assigned To"
      placeholder="Search users..."
    />
  </.form>
  """
end

def handle_event("validate", %{"task" => params}, socket) do
  changeset =
    %Task{}
    |> Task.changeset(params)
    |> Map.put(:action, :validate)

  {:noreply, assign(socket, form: to_form(changeset))}
end

Using Standalone Autocomplete

For simpler cases or when not using Phoenix forms, use the name attribute:

<.autocomplete
  name="search_user"
  options={@users}
  value={@user_id}
  placeholder="Search users..."
/>

When using standalone autocomplete:

• The name attribute determines the form field name
• Values are managed through the value attribute
• Errors are passed via the errors attribute

Input States

# Disabled state
<.autocomplete name="locked" disabled options={@options} value="locked_value" />

# Error state (standalone)
<.autocomplete name="country" options={@countries} errors={["is required"]} />

# Error state (form integration -- errors are handled automatically)
<.autocomplete field={f[:country]} options={@countries} />

Search Behavior

The autocomplete component offers flexible search strategies to handle different use cases.

Client-Side Search

Client-side search provides immediate feedback as users type, filtering the provided options directly in the browser. This is the default behavior (no on_search attribute).

Search Modes

Three search modes control how options are matched against the search query:

<.autocomplete
  name="search"
  search_mode="starts-with"
  options={["JavaScript", "TypeScript", "CoffeeScript"]}
/>

Search Threshold

Control when filtering begins based on the number of characters typed:

# No threshold -- search starts on first character (default)
<.autocomplete name="search" search_threshold={0} options={@options} />

# Require at least 2 characters before searching
<.autocomplete name="search" search_threshold={2} options={@options} />

Server-Side Search

For large datasets or dynamically computed results, enable server-side search by providing the on_search attribute with a LiveView event name:

<.autocomplete
  field={f[:user_id]}
  on_search="search_users"
  search_threshold={2}
  debounce={500}
  placeholder="Search users..."
  options={@filtered_users}
/>

When server-side search is enabled:

• The on_search event is triggered after the debounce period
• The event receives %{"query" => query, "id" => component_id} as parameters
• A loading spinner is displayed while the search is in progress
• The component reinitializes from the DOM once LiveView patches new options

def handle_event("search_users", %{"query" => query}, socket) do
  users = MyApp.Accounts.search(query) |> Enum.map(&{&1.name, &1.id})
  {:noreply, assign(socket, filtered_users: users)}
end

Search Configuration

Clearable

The clearable attribute adds a clear button (X icon) inside the input that appears when a value is selected. Clicking it resets both the visible input and the hidden form value:

<.autocomplete name="country" clearable options={@countries} placeholder="Select a country" />

When the autocomplete is disabled, the clear button is hidden regardless of the clearable setting.

Disabled Options

Individual options can be disabled using the keyword list format with a disabled key:

<.autocomplete
  name="role"
  options={[
    [key: "Admin", value: "admin"],
    [key: "Editor", value: "editor", disabled: true],
    [key: "Viewer", value: "viewer"]
  ]}
/>

Disabled options:

• Cannot be selected via click or keyboard
• Are skipped during keyboard navigation
• Display with reduced opacity and a not-allowed cursor
• Have aria-disabled="true" and data-disabled attributes

Disabled options also work within grouped options:

<.autocomplete
  name="user"
  options={[
    {"Active", [
      [key: "Alice", value: "alice"],
      [key: "Bob", value: "bob"]
    ]},
    {"Inactive", [
      [key: "Charlie", value: "charlie", disabled: true],
      [key: "Diana", value: "diana", disabled: true]
    ]}
  ]}
/>

Open on Focus

By default, the listbox opens when users start typing. Enable open_on_focus to show options immediately when the input is focused, even before any characters are typed:

<.autocomplete
  name="country"
  open_on_focus
  placeholder="Click to see all options..."
  options={@countries}
/>

Inner Affixes

Add content inside the autocomplete's border using inner affix slots. Useful for icons, status indicators, and visual elements:

<.autocomplete name="user" options={@users} placeholder="Search users...">
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="icon" />
  </:inner_prefix>
</.autocomplete>

<.autocomplete name="email" options={@emails} placeholder="user@example.com">
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-check-circle" class="icon text-green-500!" />
  </:inner_suffix>
</.autocomplete>

Outer Affixes

Place content outside the autocomplete's border using outer affix slots. Ideal for buttons, labels, and interactive elements:

<.autocomplete name="filtered" options={@options} placeholder="Search...">
  <:outer_prefix class="px-3 text-foreground-soft">Filter:</:outer_prefix>
</.autocomplete>

<.autocomplete name="with_action" options={@options} placeholder="Search...">
  <:outer_suffix>
    <.button size="md">Search</.button>
  </:outer_suffix>
</.autocomplete>

Size Matching with Affixes

When using buttons or components within affix slots, match their size attribute to the autocomplete's size for proper visual alignment:

<.autocomplete name="example" size="lg" options={@options}>
  <:outer_suffix>
    <.button size="lg">Action</.button>
  </:outer_suffix>
</.autocomplete>

Custom Option Rendering

Customize how options appear in the dropdown through the :option slot. The component passes a {label, value} tuple to the slot via :let:

<.autocomplete
  name="user"
  placeholder="Search users..."
  options={[{"Alice Chen", "alice"}, {"Bob Smith", "bob"}]}
>
  <:option :let={{label, value}}>
    <div class={[
      "flex items-center gap-3 p-2 rounded-lg",
      "in-data-highlighted:bg-zinc-100",
      "in-data-selected:font-medium"
    ]}>
      <img src={"/avatars/#{value}.jpg"} class="size-8 rounded-full" />
      <div>
        <div class="text-sm font-medium">{label}</div>
        <div class="text-xs text-zinc-500">@{value}</div>
      </div>
    </div>
  </:option>
</.autocomplete>

Option States

Custom options can respond to these data attributes for state-aware styling:

Use Tailwind's in-data-* variants to style ancestor-aware states:

<.autocomplete name="country" options={@countries}>
  <:option :let={{label, value}}>
    <div class={[
      "flex items-center gap-2 px-3 py-2 cursor-default select-none",
      "in-data-highlighted:bg-zinc-100",
      "in-data-selected:font-medium",
      "in-data-disabled:opacity-50"
    ]}>
      <.icon name={"flag-#{String.downcase(value)}"} class="size-5" />
      <span>{label}</span>
    </div>
  </:option>
</.autocomplete>

Header and Footer Content

Add custom content at the top and bottom of the listbox using the :header and :footer slots. Useful for filter buttons, action links, or informational text:

<.autocomplete field={f[:product]} options={@products}>
  <:header class="p-2 border-b">
    <div class="flex gap-2">
      <.button size="xs" class="rounded-full" phx-click="filter" phx-value-type="all">All</.button>
      <.button size="xs" class="rounded-full" phx-click="filter" phx-value-type="active">Active</.button>
    </div>
  </:header>

  <:footer class="p-2 border-t">
    <.button type="button" size="sm" class="w-full" as="link" navigate={~p"/products/new"}>
      <.icon name="u-plus" class="size-4" /> Create new
    </.button>
  </:footer>
</.autocomplete>

Both slots accept a class attribute for custom styling.

Empty State Customization

When no options match the search query, the component displays an empty state. There are two ways to customize it:

Default Text Message

Use the no_results_text attribute. The %{query} token is replaced with the search term wrapped in <strong> tags:

<.autocomplete
  name="search"
  no_results_text="No countries matching '%{query}'"
  options={@countries}
/>

Custom Empty State Slot

For richer empty states with icons, buttons, or complex layouts, use the :empty_state slot. When provided, it replaces the default text message:

<.autocomplete name="search" options={@items}>
  <:empty_state>
    <div class="p-4 text-center">
      <p class="font-medium text-zinc-500">No results found</p>
      <p class="text-sm text-zinc-400">Try a different search term</p>
    </div>
  </:empty_state>
</.autocomplete>

Keyboard Navigation

The autocomplete component implements keyboard navigation following WAI-ARIA combobox patterns:

Real-World Examples

Task Assignment with Avatars

<.autocomplete
  field={f[:assigned_to_id]}
  label="Assign To"
  description="Select a team member to assign this task"
  placeholder="Search by name..."
  clearable
  options={@users}
>
  <:inner_prefix>
    <.icon name="hero-user" class="icon" />
  </:inner_prefix>
  <:option :let={{label, value}}>
    <div class="flex items-center gap-3 p-2">
      <img src={"https://i.pravatar.cc/150?u=#{value}"} class="size-8 rounded-full" />
      <div>
        <div class="font-medium">{label}</div>
        <div class="text-sm text-zinc-500">{user_email(value)}</div>
      </div>
    </div>
  </:option>
</.autocomplete>

Server-Side Search with Preselected Value

<.autocomplete
  field={f[:customer_id]}
  on_search="search_customers"
  search_threshold={2}
  debounce={400}
  clearable
  label="Customer"
  placeholder="Type to search customers..."
  no_results_text="No customers matching '%{query}'"
  options={@customer_options}
/>

def handle_event("search_customers", %{"query" => query, "id" => _id}, socket) do
  selected_id = socket.assigns.form[:customer_id].value
  results = MyApp.Customers.search(query)

  # Always include the currently selected customer to prevent label disappearing
  options =
    if selected_id do
      selected = MyApp.Customers.get!(selected_id)
      [{selected.name, selected.id} | results] |> Enum.uniq_by(&elem(&1, 1))
    else
      results
    end

  {:noreply, assign(socket, customer_options: options)}
end

E-commerce Product Search with Groups

<.autocomplete
  name="product"
  label="Product"
  sublabel="Required"
  help_text="Start typing to search through 1000+ products"
  placeholder="Search products..."
  clearable
  search_threshold={3}
  options={[
    {"Electronics", [
      {"iPhone 15 Pro", "iphone15pro"},
      {"MacBook Air M2", "macbook-air-m2"}
    ]},
    {"Clothing", [
      {"Men's T-Shirt", "mens-tshirt"},
      {"Winter Jacket", "winter-jacket"}
    ]}
  ]}
>
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md">Browse</.button>
  </:outer_suffix>
</.autocomplete>

Custom Empty State with Create Action

<.autocomplete
  field={f[:tag_id]}
  label="Tag"
  placeholder="Search tags..."
  options={@tags}
>
  <:empty_state>
    <div class="p-4 text-center">
      <p class="font-medium text-zinc-500">No matching tags found</p>
      <.button type="button" size="sm" class="mt-2" phx-click="create_tag">
        <.icon name="u-plus" class="size-4" /> Create new tag
      </.button>
    </div>
  </:empty_state>
</.autocomplete>

Full-Featured Server Search with Custom Options

defmodule MyApp.UsersLive do
  use MyAppWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, assign(socket, users: [], form: to_form(%{}, as: :assignment))}
  end

  def render(assigns) do
    ~H\"""
    <.form :let={f} for={@form} phx-change="validate">
      <.autocomplete
        field={f[:user_id]}
        options={Enum.map(@users, &{&1.name, &1.id})}
        on_search="search_users"
        search_threshold={2}
        debounce={300}
        clearable
        label="Assign to"
        placeholder="Search users..."
      >
        <:option :let={{label, value}}>
          <div class="flex items-center gap-3 p-2 in-data-highlighted:bg-zinc-100">
            <img src={user_avatar(value, @users)} class="size-8 rounded-full" />
            <div>
              <div class="font-medium text-sm">{label}</div>
              <div class="text-xs text-zinc-500">{user_email(value, @users)}</div>
            </div>
          </div>
        </:option>
        <:empty_state>
          <div class="p-4 text-center text-zinc-500">
            <p>No matching users found</p>
            <p class="text-sm">Try searching by name or email</p>
          </div>
        </:empty_state>
      </.autocomplete>
    </.form>
    \"""
  end

  def handle_event("search_users", %{"query" => query}, socket) do
    {:noreply, assign(socket, users: MyApp.Accounts.search(query))}
  end

  def handle_event("validate", _params, socket), do: {:noreply, socket}
end