Provides <.select> component for single and multiple option selection with search, keyboard navigation, and form integration.

This module renders either a custom accessible select interface or a native HTML <select> element. The custom mode uses a hidden <select> element for form submissions while presenting a rich UI with floating listbox, typeahead, client/server search, clearable selections, grouped options, and full keyboard navigation. Multiple selection uses the HTML select multiple attribute, ensuring all form integrations (changesets, validations, etc.) work as expected.

Basic Usage

Render a select with a list of options:

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

Options can be provided in multiple formats compatible with Phoenix.HTML.Form.options_for_select/2:

• Strings: ["Option 1", "Option 2"]
• Tuples: [{"Label", "value"}, ...]
• Keyword pairs: [Admin: "admin", User: "user"]
• Keyword lists: [[key: "Admin", value: "admin"], ...]
• Atoms or integers: [:admin, :user] or [1, 2, 3]
• Grouped options: [{"Group", [{"Label", "value"}, ...]}, ...]
• Nested groups: [{"Region", [{"Country", [{"City", "id"}, ...]}, ...]}, ...]

With labels, descriptions, and a 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"}
  ]}
/>

Size Variants

Scale the select for different contexts:

<.select size="xs" name="size_xs" options={@options} />
<.select size="sm" name="size_sm" options={@options} />
<.select size="md" name="size_md" options={@options} />
<.select size="lg" name="size_lg" options={@options} />
<.select size="xl" name="size_xl" options={@options} />

Options

Grouped Options

Group related options under labels. Groups support arbitrary nesting depth, with each level receiving a CSS --depth variable for visual indentation:

<.select
  name="city"
  options={[
    {"North America", [
      {"United States", [{"New York", "ny"}, {"Los Angeles", "la"}]},
      {"Canada", [{"Toronto", "to"}, {"Vancouver", "va"}]}
    ]},
    {"Europe", [
      {"France", [{"Paris", "pa"}, {"Lyon", "ly"}]}
    ]}
  ]}
/>

Custom Option Rendering

Use the :option slot for rich content. Each option receives a {label, value} tuple:

<.select name="role" options={[{"Admin", "admin"}, {"Editor", "editor"}]}>
  <:option :let={{label, value}}>
    <div class={[
      "flex items-center justify-between rounded-lg py-2 px-3",
      "in-data-highlighted:bg-zinc-100",
      "in-data-selected:font-medium"
    ]}>
      <div>
        <div class="font-medium text-sm">{label}</div>
        <div class="text-zinc-500 text-xs">Role description here</div>
      </div>
    </div>
  </:option>
</.select>

Options expose two data attributes for styling:

• [data-highlighted]: set when the option is highlighted via keyboard or mouse hover
• [data-selected]: set when the option is currently selected

Native Select

Render a native HTML <select> element for simpler needs or mobile interfaces:

<.select name="country" native options={[{"United States", "US"}, {"Canada", "CA"}]} />

Native mode does not support search, multiple selection, custom rendering, or clearable.

Searchable

Enable client-side filtering with searchable:

<.select
  name="country"
  searchable
  search_input_placeholder="Search countries..."
  no_results_text="No countries found for %{query}."
  options={@countries}
/>

Client-side search features:

• Case-insensitive matching against option labels
• Search input auto-focuses when the dropdown opens
• Keyboard navigation works within filtered results
• Search state persists when closing and reopening

Server-Side Search

For large datasets, provide on_search 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..."
  no_results_text="No users found for '%{query}'"
  options={@filtered_users}
/>

The event receives %{"query" => query, "id" => component_id}. A loading indicator is shown while waiting for the response. The component displays an error message if the server callback fails.

Search configuration attributes:

• search_threshold: minimum characters before filtering (default: 0)
• debounce: milliseconds to wait after typing before searching (default: 300)
• on_search: LiveView event name for server-side search

Multiple Selection

Enable with the multiple attribute. The dropdown stays open after each selection:

<.select
  name="countries"
  multiple
  placeholder="Select countries"
  options={[{"United States", "US"}, {"Canada", "CA"}, {"Mexico", "MX"}]}
/>

Limit the number of selections with max:

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

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

Clearable

Add a clear button and allow deselecting the current value:

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

When clearable is enabled:

• A clear (X) button appears in the toggle when a value is selected
• Clicking a selected option in single mode deselects it
• Pressing Backspace on the toggle clears the selection
• In multiple mode, the clear button removes all selections

Affixes

Inner Affixes

Add content inside the toggle border. Icons are automatically sized to match the select's size:

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

Outer Affixes

Place content outside the toggle border for buttons, labels, or interactive elements:

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

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

Header and Footer

Add custom content at the top or bottom of the dropdown:

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

Custom Toggle

The :toggle slot replaces the entire trigger element. The default toggle ships with built-in styling, a chevron indicator, affix support, and a clear button. None of that is included when you use this slot. You are fully responsible for the toggle's appearance, layout, and any interactive affordances (placeholder text, selected value display, open/close indicator, etc.).

The slot receives a {label, value} tuple for the current selection (label is nil when nothing is selected):

<.select name="user" options={@users}>
  <:toggle :let={{label, value}}>
    <div class="flex items-center gap-2 p-2 border rounded-lg cursor-pointer hover:border-primary">
      <img src={user_avatar(value)} class="size-6 rounded-full" />
      <span class="text-sm">{label || "Select user..."}</span>
      <.icon name="hero-chevron-down" class="ml-auto size-4 text-muted" />
    </div>
  </:toggle>
</.select>

Custom Toggle Label

The :toggle_label slot is a lighter customization point that changes only how the selected value is displayed inside the toggle, while preserving all default toggle chrome (border, padding, chevron, clear button, affixes). This is ideal when you want a custom value display (e.g., badges, avatars, colored dots) without rebuilding the entire toggle.

The slot receives a {label, value} tuple for each selected option. In multiple mode, the slot is rendered once per selected item:

<.select name="status" options={@statuses}>
  <:toggle_label :let={{label, value}}>
    <span class="flex items-center gap-1.5">
      <span class={"size-2 rounded-full " <> status_color(value)} />
      {label}
    </span>
  </:toggle_label>
</.select>

Works well with multiple for tag-style rendering:

<.select name="tags" multiple options={@tags} clearable>
  <:toggle_label :let={{label, _value}}>
    <span class="inline-flex items-center px-2 py-0.5 rounded-full text-xs bg-blue-100 text-blue-800">
      {label}
    </span>
  </:toggle_label>
</.select>

Form Integration

Use the field attribute to bind to a Phoenix form field for automatic value tracking, error handling, and form submission:

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.select field={f[:country]} label="Country" options={@countries} />
  <.select field={f[:languages]} label="Languages" multiple clearable options={@languages} />
</.form>

For standalone usage without a form, use the name and value attributes directly:

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

Selection and Focus

The toggle opens on Space or Arrow Down/Arrow Up, highlighting the first, last, or currently selected option. While open, Arrow Down/Arrow Up move the highlight through the visible options without wrapping, Home and End jump to the first and last, and typing any character does a typeahead highlight by label prefix. Space (or Enter) selects the highlighted option; in multiple selection mode it toggles the option and leaves the dropdown open. Enter on the closed toggle does not open the dropdown, so it stays out of the way of form submission. Escape closes the dropdown and returns focus to the toggle, and Backspace clears the selection when clearable is enabled.

When searchable is enabled, the search input takes focus on open and drives the same highlight movement, selection, and dismissal keys against the filtered results.

LiveView Integration

The component syncs with LiveView DOM patches automatically. When the server updates the options list, the component preserves selection state, search state, open/closed state, and keyboard focus. This enables patterns like cascading selects where one select's value determines another's options.

Common Patterns

Cascading Selects

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

Searchable Multi-Select with Tags

<.select field={f[:tags]} multiple searchable clearable options={@tags} placeholder="Add tags...">
  <:toggle_label :let={{label, _value}}>
    <span class="inline-flex items-center px-2 py-0.5 rounded-full text-xs bg-blue-100 text-blue-800">
      {label}
    </span>
  </:toggle_label>
</.select>

Rich Option with Custom Rendering

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

Server-Side Search

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

Constraining the Field Width

By default, the field fills the width of its container. To narrow only the field while keeping the label, description, and help text at their natural width, apply a width utility to any ancestor that targets [data-part=field-root]:

<div class="**:data-[part=field-root]:max-w-xs">
  <.select label="Country" description="..." options={...} />
</div>

This pattern works uniformly across all Fluxon input-shaped form components.