A modern, accessible autocomplete component with rich search capabilities.

The autocomplete component provides a text input that filters a list of options as the user types, with keyboard navigation and accessibility features. It supports both client-side and server-side search capabilities, making it suitable for both small and large datasets.

Basic Usage

Simple autocomplete with a list of options:

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

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

# List of strings
<.autocomplete
  name="fruits"
  options={["Apple", "Banana", "Cherry", "Date", "Elderberry"]}
  placeholder="Search fruits..."
/>

# List of tuples (label, value)
<.autocomplete
  name="countries"
  options={[
    {"United States", "us"},
    {"Canada", "ca"},
    {"United Kingdom", "uk"},
    {"Germany", "de"}
  ]}
  placeholder="Search countries..."
/>

# Keyword list
<.autocomplete
  name="languages"
  options={[english: "en", spanish: "es", french: "fr", german: "de"]}
  placeholder="Search languages..."
/>

# Grouped options
<.autocomplete
  name="products"
  options={[
    {"Fruits", [{"Apple", "apple"}, {"Banana", "banana"}]},
    {"Vegetables", [{"Carrot", "carrot"}, {"Broccoli", "broccoli"}]},
    {"Grains", [{"Rice", "rice"}, {"Wheat", "wheat"}]}
  ]}
  placeholder="Search products..."
/>

Size Variants

The autocomplete component offers five size variants to accommodate different interface needs:

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

Each size variant adjusts the height, padding, font size, and icon dimensions proportionally:

• "xs": Extra small (h-7), suitable for compact UIs and dense layouts
• "sm": Small (h-8), good for secondary or supporting inputs
• "md": Default (h-9), recommended for most use cases
• "lg": Large (h-10), suitable for prominent or important inputs
• "xl": Extra large (h-11), ideal for hero sections or primary actions

Labels and Descriptions

Provide context and guidance with comprehensive labeling options:

# Basic label
<.autocomplete
  name="language"
  label="Programming Language"
  placeholder="Select your favorite..."
  options={["Elixir", "Phoenix", "LiveView", "Ecto", "OTP"]}
/>

# Label with sublabel
<.autocomplete
  name="database"
  label="Database"
  sublabel="Required"
  placeholder="Choose database..."
  options={["PostgreSQL", "MySQL", "SQLite", "MongoDB"]}
/>

# Label with description
<.autocomplete
  name="framework"
  label="Framework"
  description="Choose the web framework for your project"
  placeholder="Search frameworks..."
  options={["Phoenix", "Rails", "Django", "Express", "FastAPI"]}
/>

# Complete example with all text features
<.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"]}
/>

Form Integration

The autocomplete component integrates with Phoenix forms in two ways: using the field attribute for 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[:user_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
• Nested form data handling

Complete example with 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..."
/>

Input States

The autocomplete component supports various input states for different use cases:

Disabled State

Disable the autocomplete to prevent user interaction:

# Disabled empty autocomplete
<.autocomplete
  name="disabled_empty"
  label="Unavailable Option"
  disabled
  placeholder="This option is currently disabled"
  options={["Option 1", "Option 2", "Option 3"]}
/>

# Disabled with pre-selected value
<.autocomplete
  name="disabled_selected"
  label="Read-only Selection"
  disabled
  value="Option 2"
  options={["Option 1", "Option 2", "Option 3"]}
/>

Error States

Display validation errors below the autocomplete:

# Single error
<.autocomplete
  name="single_error"
  label="Required Field"
  placeholder="This field is required"
  options={["Option 1", "Option 2", "Option 3"]}
  errors={["This field is required"]}
/>

# Multiple errors
<.autocomplete
  name="multiple_errors"
  label="Field with Multiple Issues"
  placeholder="Multiple validation errors"
  options={["Option 1", "Option 2", "Option 3"]}
  errors={["This field is required", "Please select a valid option"]}
/>

Inner Affixes

Use the :inner_prefix and :inner_suffix slots to add content inside the autocomplete's border. This is useful for icons, status indicators, or visual enhancements that should appear within the input field.

# Search icon prefix
<.autocomplete name="user_search" options={@users} placeholder="Search users...">
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
</.autocomplete>

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

# Location search with emoji
<.autocomplete name="location" options={@locations} placeholder="City name">
  <:inner_prefix class="text-foreground-softest">📍</:inner_prefix>
</.autocomplete>

# Both inner affixes combined
<.autocomplete name="comprehensive" options={@options} placeholder="Search...">
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-information-circle" class="size-4" />
  </:inner_suffix>
</.autocomplete>

Outer Affixes

Use the :outer_prefix and :outer_suffix slots to add content outside the autocomplete's border. This is ideal for buttons, labels, or interactive elements that complement the search functionality.

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

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

# User invitation with send button
<.autocomplete name="invite_user" options={@users} placeholder="Search users...">
  <:inner_prefix>
    <.icon name="hero-user-plus" class="size-4" />
  </:inner_prefix>
  <:outer_suffix>
            <.button variant="solid" color="primary" size="md">
      <.icon name="hero-paper-airplane" class="size-4" /> Invite
    </.button>
  </:outer_suffix>
</.autocomplete>

# All affixes combined
<.autocomplete name="comprehensive" options={@options} placeholder="Search...">
  <:outer_prefix class="px-2">Search</:outer_prefix>
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-information-circle" class="size-4" />
  </:inner_suffix>
  <:outer_suffix>
    <.button size="md">Go</.button>
  </:outer_suffix>
</.autocomplete>

Size Matching with Affixes

When using buttons or other components within affix slots, ensure their size attribute matches the autocomplete's size for proper visual alignment. For example, if the autocomplete is size="lg", use buttons with size="lg" as well.

Search Behavior

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

Client-side Search

Client-side search provides immediate feedback as users type, filtering the provided options directly in the browser. This approach is ideal for small to medium datasets.

Search Modes

Control how options are matched against the search query:

# Contains (default) - matches anywhere in the option
<.autocomplete
  name="contains_search"
  label="Contains Search"
  search_mode="contains"
  placeholder="Type any part of the word..."
  options={["JavaScript", "TypeScript", "CoffeeScript", "ReScript"]}
/>

# Starts with - matches only at the beginning
<.autocomplete
  name="starts_with_search"
  label="Starts With Search"
  search_mode="starts-with"
  placeholder="Type beginning of word..."
  options={["JavaScript", "TypeScript", "CoffeeScript", "ReScript"]}
/>

# Exact match - requires exact matching
<.autocomplete
  name="exact_search"
  label="Exact Match"
  search_mode="exact"
  placeholder="Type exact match..."
  options={["JavaScript", "TypeScript", "CoffeeScript", "ReScript"]}
/>

Search Thresholds

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

# No threshold - search immediately
<.autocomplete
  name="no_threshold"
  label="Immediate Search"
  search_threshold={0}
  placeholder="Search immediately..."
  options={["React", "Vue", "Angular", "Svelte", "Solid"]}
/>

# 2 character threshold
<.autocomplete
  name="threshold_2"
  label="2 Character Minimum"
  search_threshold={2}
  placeholder="Type 2+ characters..."
  options={["React", "Vue", "Angular", "Svelte", "Solid"]}
/>

# 3 character threshold
<.autocomplete
  name="threshold_3"
  label="3 Character Minimum"
  search_threshold={3}
  placeholder="Type 3+ characters..."
  options={["React", "Vue", "Angular", "Svelte", "Solid"]}
/>

Server-side Search

For large datasets, dynamic data sources, or when complex search logic is required, the component supports server-side search through LiveView integration:

<.autocomplete
  name="movie"
  options={@movies}
  on_search="search_movies"
  search_threshold={2}
  placeholder="Type to search movies..."
/>

In your LiveView, handle the search event to fetch and update the options:

def mount(_params, _session, socket) do
  {:ok, assign(socket, movies: [])}
end

def handle_event("search_movies", %{"query" => query}, socket) when byte_size(query) >= 2 do
  case MyApp.Movies.search(query) do
    {:ok, movies} ->
      {:noreply, assign(socket, movies: movies)}
    {:error, _reason} ->
      {:noreply, assign(socket, movies: [])}
  end
end

The component automatically manages the search state, including:

• Debouncing requests to prevent excessive server calls
• Displaying a loading indicator during searches
• Maintaining the selected value while searching
• Handling empty states and error conditions

⚠️ Selected Value and Initial Options

When using server-side search with a selected value, ensure that the selected option is included in the initial options list:

def mount(_params, _session, socket) do
  featured_users = MyApp.Accounts.featured_users() |> Enum.map(&{&1.name, &1.id})
  selected_user = MyApp.Accounts.get_user!(2)

  # Good: Include the selected user in initial options
  {:ok, assign(socket,
    selected_user_id: selected_user.id,
    users: [{selected_user.name, selected_user.id} | featured_users]
  )}
end

Advanced Features

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:

# Normal behavior - opens when typing
<.autocomplete
  name="normal"
  label="Normal Behavior"
  placeholder="Type to see options..."
  options={["Option 1", "Option 2", "Option 3"]}
/>

# Opens immediately on focus
<.autocomplete
  name="open_on_focus"
  label="Open on Focus"
  open_on_focus
  placeholder="Click to see all options..."
  options={["Option 1", "Option 2", "Option 3"]}
/>

Clearable Selection

Add a clear button to allow users to easily reset their selection:

# Not clearable (default)
<.autocomplete
  name="not_clearable"
  label="Standard Autocomplete"
  placeholder="No clear button..."
  options={["Option 1", "Option 2", "Option 3"]}
/>

# Clearable - adds × button when value is selected
<.autocomplete
  name="clearable"
  label="Clearable Autocomplete"
  clearable
  placeholder="Has clear button when selected..."
  options={["Option 1", "Option 2", "Option 3"]}
/>

# Clearable with initial value
<.autocomplete
  name="clearable_with_value"
  label="Pre-selected with Clear"
  clearable
  value="Option 2"
  options={["Option 1", "Option 2", "Option 3"]}
/>

Custom Option Rendering

The autocomplete component supports rich, custom option rendering through the :option slot. Each option receives a tuple {label, value} that you can use to create sophisticated option displays:

# User selection with avatars
<.autocomplete
  name="users"
  label="Assign Task To"
  placeholder="Search team members..."
  options={[
    {"John Doe", "john"},
    {"Jane Smith", "jane"},
    {"Bob Johnson", "bob"},
    {"Alice Brown", "alice"}
  ]}
>
  <:option :let={{label, value}}>
    <div class="flex items-center gap-3 p-2 rounded-lg in-data-highlighted:bg-zinc-100 in-data-selected:bg-blue-100">
      <div class="size-8 rounded-full bg-gradient-to-r from-blue-500 to-purple-500 flex items-center justify-center text-white text-sm font-bold">
        {String.first(label)}
      </div>
      <div>
        <div class="font-medium text-sm">{label}</div>
        <div class="text-xs text-zinc-500">@{value}</div>
      </div>
    </div>
  </:option>
</.autocomplete>

# Product selection with status and icons
<.autocomplete
  name="products"
  label="Select Product"
  placeholder="Search inventory..."
  options={[
    {"MacBook Pro 16\"", "mbp16"},
    {"MacBook Air 13\"", "mba13"},
    {"iMac 24\"", "imac24"},
    {"Mac Studio", "studio"}
  ]}
>
  <:option :let={{label, value}}>
    <div class="flex items-center justify-between p-2 rounded-lg in-data-highlighted:bg-zinc-100">
      <div class="flex items-center gap-3">
        <div class="size-10 rounded bg-zinc-100 flex items-center justify-center">
          <.icon name="hero-computer-desktop" class="size-5 text-zinc-600" />
        </div>
        <div>
          <div class="font-medium text-sm">{label}</div>
          <div class="text-xs text-zinc-500">Model: {value}</div>
        </div>
      </div>
      <div class="text-xs text-green-600 font-medium">In Stock</div>
    </div>
  </:option>
</.autocomplete>

Header and Footer Content

Add custom content at the top and bottom of the listbox using the :header and :footer slots:

# Simple header
<.autocomplete field={f[:category]} options={@categories}>
  <:header class="p-3 border-b border-base bg-zinc-50">
    <div class="text-sm font-medium text-zinc-700">Popular Categories</div>
  </:header>
</.autocomplete>

# Footer with action button
<.autocomplete field={f[:item]} options={@items}>
  <:footer class="p-2 border-t border-base">
    <.button type="button" size="sm" class="w-full">
      <.icon name="hero-plus" class="size-4" /> Create New Item
    </.button>
  </:footer>
</.autocomplete>

# Both header and footer with filters
<.autocomplete field={f[:product]} options={@products}>
  <:header class="p-2 border-b border-base">
    <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>
      <.button size="xs" class="rounded-full" phx-click="filter" phx-value-type="draft">Draft</.button>
    </div>
  </:header>
  <:footer class="p-2 border-t border-base">
    <.button type="button" size="sm" class="w-full" variant="tertiary">
      <.icon name="hero-plus" class="size-4" /> Add New Product
    </.button>
  </:footer>
</.autocomplete>

Empty State Customization

Customize the message displayed when no options match the search query:

# Default empty state
<.autocomplete
  name="default_empty"
  label="Default Empty Message"
  no_results_text="No results found for '%{query}'"
  placeholder="Search to see default message..."
  options={["Apple", "Banana", "Cherry"]}
/>

# Custom empty state with icon and actions
<.autocomplete
  name="custom_empty"
  label="Custom Empty State"
  placeholder="Search to see custom empty state..."
  options={["Apple", "Banana", "Cherry"]}
>
  <:empty_state>
    <div class="p-4 text-center">
      <div class="text-zinc-400">
        <.icon name="hero-face-frown" class="size-8 mx-auto mb-2" />
        <p class="font-medium">No results found</p>
        <p class="text-sm">Try a different search term or check your spelling</p>
      </div>
    </div>
  </:empty_state>
</.autocomplete>

Keyboard Support

The autocomplete component provides comprehensive keyboard navigation:

Real-world Examples

Task Assignment Interface

<.autocomplete
  name="assigned_user"
  label="Assign Task To"
  description="Select a team member to assign this task"
  placeholder="Search by name or email..."
  clearable
  search_threshold={2}
  options={[
    {"John Doe (john@example.com)", "john"},
    {"Jane Smith (jane@example.com)", "jane"},
    {"Bob Johnson (bob@example.com)", "bob"}
  ]}
>
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
  <:option :let={{label, value}}>
    <div class="flex items-center gap-3 p-2">
      <div class="size-8 rounded-full bg-blue-500 flex items-center justify-center text-white text-sm font-bold">
        {String.first(label)}
      </div>
      <div class="flex-1">
        <div class="font-medium text-sm">{String.split(label, " (") |> hd()}</div>
        <div class="text-xs text-zinc-500">
          {String.split(label, "(") |> Enum.at(1, "") |> String.replace(")", "")}
        </div>
      </div>
    </div>
  </:option>
</.autocomplete>

E-commerce Product Search

<.autocomplete
  name="product_search"
  label="Product Catalog"
  sublabel="Required"
  description="Choose a product from our catalog"
  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"},
       {"AirPods Pro 2", "airpods-pro-2"}
     ]},
    {"Clothing",
     [
       {"Men's T-Shirt", "mens-tshirt"},
       {"Women's Jeans", "womens-jeans"},
       {"Winter Jacket", "winter-jacket"}
     ]}
  ]}
>
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="size-4" />
  </:inner_prefix>
  <:outer_suffix>
    <.button size="md">Browse</.button>
  </:outer_suffix>
  <:header class="p-2 border-b border-base bg-zinc-50">
    <div class="text-sm text-zinc-600">🔥 Popular products shown first</div>
  </:header>
  <:footer class="p-2 border-t border-base">
    <.button type="button" size="sm" class="w-full" variant="ghost">
      Can't find what you're looking for? <span class="text-blue-600">Contact us</span>
    </.button>
  </:footer>
</.autocomplete>

Server-side User Search

defmodule MyApp.UsersLive do
  use MyAppWeb, :live_view

  def mount(_params, _session, socket) do
    {:ok, socket |> assign(users: fetch_users()) |> assign(form: to_form(%{}, as: :search))}
  end

  def render(assigns) do
    ~H"""
    <.form :let={f} for={@form} phx-change="search">
      <.autocomplete field={f[:user_id]} options={user_options(@users)} on_search="search_users" clearable>
        <:option :let={{label, value}}>
          <div class="flex items-center gap-3 p-2 rounded-lg in-data-highlighted:bg-zinc-100 in-data-selected:bg-blue-100">
            <img src={user_by_id(value, @users)["image"]} class="size-8 rounded-full" />
            <div>
              <div class="font-medium text-sm">{label}</div>
              <div class="text-xs text-zinc-500">{user_by_id(value, @users)["email"]}</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: fetch_users(query))}
  end

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

  defp fetch_users(query \\ "") do
    case Req.get("https://dummyjson.com/users/search", params: [limit: 10, q: query]) do
      {:ok, %{body: %{"users" => users}}} -> users
      _ -> []
    end
  end

  defp user_options(users), do: Enum.map(users, &{&1["firstName"] <> " " <> &1["lastName"], &1["id"]})
  defp user_by_id(id, users), do: Enum.find(users, &(&1["id"] == id))
end