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.

Usage

Basic usage 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:

• List of strings: ["Option 1", "Option 2"]
• List of tuples: [{"Label 1", "value1"}, {"Label 2", "value2"}]
• List of keyword pairs: [key: "value"]
• Grouped options: [{"Group", ["Option 1", "Option 2"]}]

A full-feature example would look like this:

<.autocomplete
  name="user"
  label="Select User"
  sublabel="Search by name or email"
  description="Choose a user to assign the task to"
  help_text="Type to search through all registered users"
  placeholder="Search users..."
  search_threshold={3}
  options={@users}
/>

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

Example with a complete 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

Search Behavior

The autocomplete component offers two distinct search strategies: client-side and server-side filtering. This flexibility allows the component to efficiently handle both small, static datasets and large, dynamic data sources that require server-side processing.

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 that do not require server-side processing, such as language selections, predefined categories, list of countries, etc.

<.autocomplete
  name="language"
  search_mode="contains"
  search_threshold={2}
  no_results_text="No languages matching '%{query}'"
  options={[
    {"English", "en"},
    {"Spanish", "es"},
    {"French", "fr"},
    {"German", "de"}
  ]}
/>

The component offers three search modes through the search_mode attribute, each providing different matching behavior:

• "contains" (default): Matches if the option label contains the search query anywhere
• "starts-with": Matches only if the option label begins with the search query
• "exact": Matches only if the option label exactly matches the search query

The search_threshold attribute determines how many characters must be typed before filtering begins, helping to prevent unnecessary filtering operations for very short queries.

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. This is particularly useful when dealing with database queries, API calls, or when implementing features like debounced search or typeahead suggestions.

Server-side search is activated by providing the on_search attribute with a LiveView event name. When users type, the component sends this event with the search query as a parameter:

<.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

Initial Options

While server-side search is primarily focused on dynamic filtering, you can optionally provide an initial set of options that will be available when the component loads:

def mount(_params, _session, socket) do
  {:ok, assign(socket, movies: MyApp.Movies.featured_movies())}
end

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

These initial options are accessible as soon as the user interacts with the component, whether by clicking the input field, using arrow keys (↑/↓), or focusing the input when open_on_focus is enabled.

The choice between providing initial options or starting with an empty list depends on your use case:

• Initial Options: Ideal when you want to showcase popular or recommended choices upfront, reducing the need for typing and improving discoverability. This works well for scenarios like movie recommendations, frequently used items, or recently accessed content.

• Empty Initial State: Better suited when the dataset is too large to meaningfully preload options, when you want to encourage specific search terms, or when options are highly contextual to the user's input. This is common in scenarios like user search in large organizations or product search in extensive catalogs.

⚠️ Selected Value and Initial Options

When the component is initialized with a value, it attempts to find the corresponding label from the provided options to display in the input. For example, if the component is initialized with value={2} and the options include {"Alice", 2}, the input will display "Alice" as the selected value.

def mount(_params, _session, socket) do
  # Bad: Selected user (id: 2) is not included in initial options
  {:ok, assign(socket,
    selected_user_id: 2,
    users: []  # Empty initial options
  )}
end

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

When using server-side search with a selected value, it's crucial to ensure that the selected option is included in the initial options list, even if you're starting with an otherwise empty list. If the selected value's option is not found in the list, the raw value will be displayed in the input, resulting in a poor user experience.

Custom Option Rendering

The autocomplete component supports custom option rendering through its :option slot. For each option in the list, the component passes a tuple {label, value} to the slot:

<.autocomplete
  name="user"
  options={@users}
  placeholder="Search users..."
>
  <:option :let={{label, value}}>
    <div class={[
      "flex items-center gap-3 p-2",
      "[[data-highlighted]_&]:bg-zinc-100 dark:[[data-highlighted]_&]:bg-zinc-800",
      "[[data-selected]_&]:font-medium"
    ]}>
      <img src={user_avatar_url(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>

Empty State

The autocomplete component also supports a custom empty state through the :empty_state slot:

<.autocomplete options={@users}>
  <:empty_state>
    <div class="p-4 text-center">
      <div class="text-zinc-400 dark:text-zinc-500">
        <.icon name="u-user-x" class="size-8 mx-auto mb-2" />
        <p>No users found</p>
        <p class="text-sm">Try a different search term</p>
      </div>
    </div>
  </:empty_state>
</.autocomplete>

Keyboard Support

The autocomplete component provides comprehensive keyboard navigation:

Common Use Cases

User Search with Avatar

defmodule MyApp.UsersLive do
  use FluxlandWeb, :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">
        <:option :let={{label, value}}>
          <div class="flex items-center gap-3 p-2 rounded-lg [[data-highlighted]_&]:bg-zinc-100 [[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