A modern, accessible select component for building rich selection interfaces in Phoenix LiveView.

The select component provides single and multiple selection, client-side and server-side search, custom option rendering, grouped and nested options, and full keyboard navigation. It operates in two modes: a feature-rich custom select (default) backed by a hidden <select> element for form compatibility, and a lightweight native mode that renders the browser's built-in <select> control.

Usage

Basic usage with a list of options:

<.select
  name="country"
  options={[{"United States", "us"}, {"Canada", "ca"}]}
/>

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

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

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

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

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

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

# Multi-level nested groups (flattened with visual indentation)
<.select
  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:

<.select
  name="payment_method"
  label="Payment Method"
  sublabel="Required"
  description="Choose your preferred payment method"
  help_text="We securely process all payment information"
  placeholder="Select payment method"
  options={[
    {"Credit Card", "credit_card"},
    {"PayPal", "paypal"},
    {"Bank Transfer", "bank_transfer"},
    {"Cryptocurrency", "crypto"}
  ]}
/>

Native Select

Set native to render a standard HTML <select> element instead of the custom interface. This is ideal for mobile-first designs, simple forms, or when maximum browser compatibility is required.

<.select
  name="country"
  native
  placeholder="Pick a country"
  options={[{"United States", "us"}, {"Canada", "ca"}]}
/>

Size Variants

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

<.select name="xs" size="xs" options={@options} placeholder="Extra small" />
<.select name="sm" size="sm" options={@options} placeholder="Small" />
<.select name="md" size="md" options={@options} placeholder="Medium (default)" />
<.select name="lg" size="lg" options={@options} placeholder="Large" />
<.select 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
<.select name="country" label="Country" options={@countries} />

# Label with sublabel
<.select name="country" label="Country" sublabel="Required" options={@countries} />

# Label with description
<.select
  name="country"
  label="Country"
  description="Where is your company headquartered?"
  options={@countries}
/>

# Complete example with help text
<.select
  name="country"
  label="Country"
  sublabel="Optional"
  description="Used for tax calculation purposes"
  help_text="You can change this later in settings"
  placeholder="Select a country..."
  options={@countries}
/>

Form Integration

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

Using with Phoenix Forms (Recommended)

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

<.form :let={f} for={@changeset} phx-change="validate" phx-submit="save">
  <.select
    field={f[:country]}
    label="Country"
    options={@countries}
  />
</.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
• Nested form data handling

Complete example with a changeset implementation:

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

  schema "users" do
    field :country, :string
    field :languages, {:array, :string}
    timestamps()
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:country, :languages])
    |> validate_required([:country])
    |> validate_subset(:languages, ["en", "es", "fr", "de"])
  end
end

# In your LiveView
def mount(_params, _session, socket) do
  countries = [{"United States", "us"}, {"Canada", "ca"}, {"Mexico", "mx"}]
  languages = [{"English", "en"}, {"Spanish", "es"}, {"French", "fr"}, {"German", "de"}]

  changeset = User.changeset(%User{}, %{})

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

def render(assigns) do
  ~H"""
  <.form :let={f} for={@form} phx-change="validate">
    <.select clearable field={f[:country]} options={@countries} label="Country" />
    <.select clearable multiple field={f[:languages]} options={@languages} label="Languages" />
  </.form>
  """
end

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

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

Using Standalone Selects

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

<.select
  name="sort_by"
  value="newest"
  options={[
    {"Newest First", "newest"},
    {"Oldest First", "oldest"},
    {"Name A-Z", "name_asc"}
  ]}
/>

When using standalone selects:

• 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
<.select name="locked" disabled options={@options} value="locked_value" />

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

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

Searchable

Enable the built-in search input to filter options by setting searchable:

<.select
  name="country"
  searchable
  search_input_placeholder="Search for a country"
  search_no_results_text="No countries found for %{query}"
  options={[
    {"United States", "us"},
    {"Canada", "ca"},
    {"Mexico", "mx"}
  ]}
/>

Search Behavior

Client-side search provides immediate feedback with these characteristics:

• Case-insensitive matching
• Diacritics-insensitive (accents are ignored via Unicode normalization)
• Filters update as you type
• Full keyboard navigation remains active during search
• Search input receives focus automatically when the select opens

The search matches against option labels. For example, searching for "united" will match "United States" regardless of case or accents.

Custom Search Messages

Two attributes control the search text:

• search_input_placeholder: Text shown in the search input (default: "Search...")
• search_no_results_text: Text shown when no options match (default: "No results found for %{query}.")

The no results message can include the search term with %{query}:

<.select
  name="country"
  searchable
  search_input_placeholder="Find a country..."
  search_no_results_text="No countries matching '%{query}'"
  options={@countries}
/>

Search with Multiple Selection

When combining search and multiple selection, the component preserves the selected state of filtered-out options. Selected labels remain visible in the toggle button even when those options are hidden by the search filter:

<.select
  name="countries"
  multiple
  searchable
  options={@countries}
  placeholder="Select countries"
  search_input_placeholder="Search countries..."
/>

Search with Custom Options

Search matches against option labels while preserving your custom rendering:

<.select name="user" searchable options={@users}>
  <:option :let={{label, value}}>
    <div class="flex items-center gap-2 px-3 py-2">
      <img src={avatar_url(value)} class="size-8 rounded-full" />
      <div>
        <div class="font-medium">{label}</div>
        <div class="text-sm text-zinc-500">{user_role(value)}</div>
      </div>
    </div>
  </:option>
</.select>

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:

<.select
  field={f[:user_id]}
  searchable
  search_threshold={2}
  debounce={500}
  on_search="search_users"
  search_input_placeholder="Search users..."
  search_no_results_text="No users found for '%{query}'"
  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

Search Configuration

Example with all search options configured:

<.select
  field={f[:product_id]}
  searchable
  search_threshold={3}
  debounce={400}
  on_search="search_products"
  search_input_placeholder="Type at least 3 characters to search..."
  search_no_results_text="No products found matching '%{query}'"
  options={@products}
/>

Multiple Selection

Enable multiple selection with the multiple attribute:

<.select
  name="countries"
  multiple
  placeholder="Select countries"
  options={[{"United States", "us"}, {"Canada", "ca"}, {"Mexico", "mx"}]}
/>

This allows selecting multiple options and submits an array of values:

%{"_target" => ["countries"], "countries" => ["", "us", "ca", "mx"]}

<input type="hidden" name="countries[]" value="" />
<select multiple name="countries[]">
  <!-- options here -->
</select>

# No options selected
%{"countries" => [""]}

# One or more selected
%{"countries" => ["", "us", "ca"]}

selected = Enum.reject(params["countries"] || [], &(&1 == ""))

By default, there is no limit on the number of selections.

Maximum Selections

Use the max attribute to cap the number of selections:

<.select name="tags" multiple max={3} options={@tags} placeholder="Select up to 3 tags" />

When the maximum is reached, additional options become unselectable until an existing selection is removed.

Clearable

By default, single selections cannot be unselected. The clearable attribute adds a clear button and enables re-clicking a selected option to deselect it. Pressing Backspace when the toggle is focused also clears the selection. For multiple selections, the clear button removes all selections at once.

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

When clearing a single selection, the empty placeholder option (<option value="">) is selected, sending an empty string in the form data -- consistent with how multiple select handles empty states.

Disabled Options

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

<.select
  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 arrow key navigation
• Are skipped during typeahead matching
• Display with reduced opacity and a not-allowed cursor
• Have aria-disabled="true" and data-disabled attributes

Disabled options also work within grouped options:

<.select
  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]
    ]}
  ]}
/>

Inner Affixes

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

<.select name="category" options={@categories} placeholder="Select category">
  <:inner_prefix>
    <.icon name="hero-folder" class="icon" />
  </:inner_prefix>
</.select>

<.select name="status" options={@statuses} placeholder="Select status">
  <:inner_prefix>
    <.icon name="hero-flag" class="icon" />
  </:inner_prefix>
  <:inner_suffix>
    <.icon name="hero-check-circle" class="icon text-green-500!" />
  </:inner_suffix>
</.select>

Outer Affixes

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

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

<.select name="with_action" options={@options} placeholder="Select option">
  <:outer_suffix>
    <.button size="md">Apply</.button>
  </:outer_suffix>
</.select>

Size Matching with Affixes

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

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

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:

<.select
  name="role"
  placeholder="Select role"
  options={[
    {"Admin", "admin"},
    {"Editor", "editor"},
    {"Viewer", "viewer"}
  ]}
>
  <:option :let={{label, value}}>
    <div class={[
      "flex items-center justify-between",
      "rounded-lg py-2 px-3",
      "in-data-selected:bg-zinc-100",
      "in-data-highlighted:bg-zinc-50"
    ]}>
      <div>
        <div class="font-medium text-sm">{label}</div>
        <div class="text-zinc-500 text-xs">
          {case value do
            "admin" -> "Full access to all features"
            "editor" -> "Can create and modify content"
            "viewer" -> "Read-only access to content"
          end}
        </div>
      </div>
      <.icon :if={value == "admin"} name="u-shield-check" class="size-4 text-blue-500" />
    </div>
  </:option>
</.select>

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:

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

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:

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

Both slots accept a class attribute for custom styling.

Keyboard Navigation

The select component implements comprehensive keyboard navigation following WAI-ARIA listbox patterns:

When searchable is enabled, the search input receives focus when the listbox opens, and all keyboard navigation keys continue to work from the search input.

For multiple selection mode:

• Enter toggles the selection state without closing the listbox
• The listbox stays open for additional choices
• Focus is maintained on the search input (when searchable) after each selection

Typeahead

When the listbox is closed, typing characters selects the matching option directly. When open, typing highlights the match. Characters accumulate for 300ms, then reset. Disabled options are skipped during typeahead.

<.form :let={f} for={@form} phx-change="validate">
  <.select field={f[:country]} options={@countries} label="Country" searchable />
</.form>

def handle_event("add_country", %{"country" => params}, socket) do
  updated_countries = [{params["name"], params["code"]} | socket.assigns.countries]
  {:noreply, assign(socket, :countries, updated_countries)}
end

<.select
  name="custom_anim"
  options={@options}
  animation="transition duration-200 ease-out"
  animation_enter="opacity-100 translate-y-0"
  animation_leave="opacity-0 -translate-y-1"
/>

Real-World Examples

Cascading Selects

Dependent select fields where selecting a value in one field determines the options in the next:

<.form :let={f} for={@location} phx-change="update">
  <.select
    field={f[:country]}
    options={@countries}
    label="Country"
    placeholder="Select a country..."
    clearable
  />
  <.select
    field={f[:state]}
    options={@states}
    label="State"
    placeholder="Select a state..."
    disabled={@states == []}
    clearable
  />
  <.select
    field={f[:city]}
    options={@cities}
    label="City"
    placeholder="Select a city..."
    disabled={@cities == []}
  />
</.form>

def mount(_params, _session, socket) do
  {:ok,
   assign(socket,
     countries: [{"United States", "us"}, {"Brazil", "br"}],
     states: [],
     cities: [],
     location: to_form(%{})
   )}
end

def handle_event("update", %{"location" => params}, socket) do
  case params do
    %{"country" => country} when country != "" ->
      states = fetch_states_for_country(country)
      {:noreply, assign(socket, states: states, cities: [], location: to_form(params))}

    %{"country" => country, "state" => state} when country != "" and state != "" ->
      cities = fetch_cities_for_state(state)
      {:noreply, assign(socket, cities: cities, location: to_form(params))}

    _ ->
      {:noreply, assign(socket, states: [], cities: [], location: to_form(params))}
  end
end

User Assignment with Avatars

<.select field={f[:assigned_to]} searchable options={@users} placeholder="Assign to...">
  <: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>
</.select>

Tag Picker with Maximum Limit

<.select
  field={f[:tags]}
  multiple
  max={5}
  searchable
  clearable
  label="Tags"
  sublabel="Up to 5"
  placeholder="Select tags..."
  search_input_placeholder="Search tags..."
  options={@available_tags}
/>

Product Filter with Header Actions

<.select name="product" options={@products} placeholder="Filter products...">
  <:header class="p-2 border-b">
    <div class="flex gap-2">
      <.button size="xs" phx-click="filter" phx-value-category="all">All</.button>
      <.button size="xs" phx-click="filter" phx-value-category="active">Active</.button>
      <.button size="xs" phx-click="filter" phx-value-category="archived">Archived</.button>
    </div>
  </:header>
  <:footer class="p-2 border-t">
    <.button size="sm" class="w-full" as="link" navigate={~p"/products/new"}>
      <.icon name="u-plus" class="size-4" /> Add Product
    </.button>
  </:footer>
</.select>

Server-Side Search with Preselected Value

<.select
  field={f[:customer_id]}
  searchable
  on_search="search_customers"
  search_threshold={2}
  debounce={400}
  clearable
  label="Customer"
  search_input_placeholder="Type to search customers..."
  search_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