SutraUI.Select (Sutra UI v0.2.0)

A custom select component with search/filter capabilities (combobox pattern).

Provides a fully accessible dropdown select with keyboard navigation, optional search filtering, option grouping, and form integration. Use this instead of native <select> when you need custom styling or searchable options.

Examples

# Basic select
<.select id="country" name="country" value="us">
  <.select_option value="us" label="United States" />
  <.select_option value="ca" label="Canada" />
  <.select_option value="mx" label="Mexico" />
</.select>

# Searchable select
<.select id="framework" name="framework" value="phoenix" searchable>
  <.select_option value="phoenix" label="Phoenix" />
  <.select_option value="rails" label="Rails" />
  <.select_option value="django" label="Django" />
  <.select_option value="laravel" label="Laravel" />
</.select>

# With option groups
<.select id="stack" name="stack" value="phoenix" searchable>
  <.select_group label="Backend">
    <.select_option value="phoenix" label="Phoenix" />
    <.select_option value="rails" label="Rails" />
  </.select_group>
  <.select_separator />
  <.select_group label="Frontend">
    <.select_option value="react" label="React" />
    <.select_option value="vue" label="Vue" />
  </.select_group>
</.select>

# With custom trigger content
<.select id="status" name="status" value={@status}>
  <:trigger>
    <.badge variant={status_variant(@status)}>{@status}</.badge>
  </:trigger>
  <.select_option value="active" label="Active" />
  <.select_option value="pending" label="Pending" />
  <.select_option value="inactive" label="Inactive" />
</.select>

Components

Component	Description
`select/1`	Main container with trigger and popover
`select_option/1`	Individual selectable option
`select_group/1`	Labeled group of options
`select_separator/1`	Visual divider between options/groups

Keyboard Navigation

Key	Action
`Enter` / `Space`	Open dropdown or select focused option
`Escape`	Close dropdown
`ArrowDown`	Move to next option
`ArrowUp`	Move to previous option
`Home`	Jump to first option
`End`	Jump to last option
`A-Z`	Jump to first option starting with letter

Form Integration

The select renders a hidden <input> with the selected value, making it compatible with Phoenix forms and phx-change events:

<.simple_form for={@form} phx-change="validate" phx-submit="save">
  <.select
    id="role-select"
    name={@form[:role].name}
    value={@form[:role].value}
  >
    <.select_option value="admin" label="Administrator" />
    <.select_option value="user" label="User" />
  </.select>
</.simple_form>

Colocated Hook

The .Select hook handles all interactive behavior:

Opening/closing the dropdown popover
Keyboard navigation and letter jumping
Search filtering (when searchable)
Value selection and form change event dispatch
Outside click detection

See JavaScript Hooks for more details.

Accessibility

Implements WAI-ARIA combobox pattern
role="listbox" for the options container
role="option" for each selectable item
aria-selected indicates current selection
aria-expanded reflects dropdown state
aria-controls links trigger to listbox
aria-disabled for disabled options

Required ID

The id attribute is required for the JavaScript hook to function. Each select must have a unique ID on the page.

SutraUI.LiveSelect - For async/remote data loading
SutraUI.RadioGroup - For smaller option sets without dropdown
SutraUI.DropdownMenu - For action menus (not form selection)
Forms Cheatsheet - Form patterns
Accessibility Guide - ARIA patterns

Summary

Functions

select(assigns)

Renders a custom select component.

select_group(assigns)

Renders a select option group.

select_option(assigns)

Renders a select option.

select_separator(assigns)

Renders a separator between select options or groups.

Functions

select(assigns)

Renders a custom select component.

Examples

<.select id="country-select" name="country" value="us">
  <.select_option value="us" label="United States" />
  <.select_option value="ca" label="Canada" />
  <.select_option value="mx" label="Mexico" />
</.select>

<.select id="framework-select" name="framework" value="phoenix" searchable>
  <.select_group label="Frontend">
    <.select_option value="react" label="React" />
    <.select_option value="vue" label="Vue" />
  </.select_group>
  <.select_separator />
  <.select_group label="Backend">
    <.select_option value="phoenix" label="Phoenix" />
    <.select_option value="rails" label="Rails" />
  </.select_group>
</.select>

<.select id="status-select" name="status" value="active" disabled>
  <.select_option value="active" label="Active" />
  <.select_option value="inactive" label="Inactive" />
</.select>

Attributes

id (:string) (required) - Unique identifier for the select (required for hook).
name (:string) - Form input name. Defaults to nil.
value (:string) - Currently selected value. Defaults to nil.
searchable (:boolean) - Enable search/filter functionality. Defaults to false.
search_placeholder (:string) - Placeholder text for search input. Defaults to "Search entries...".
empty_message (:string) - Message when no results match search. Defaults to "No results found".
trigger_class (:string) - Additional CSS classes for trigger button. Defaults to nil.
class (:string) - Additional CSS classes for main container. Defaults to nil.
disabled (:boolean) - Whether the select is disabled. Defaults to false.
Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["form", "phx-change", "phx-blur", "phx-focus"].

Slots

trigger - Custom content for the trigger button (optional).
inner_block (required) - The select options and groups.

select_group(assigns)

Renders a select option group.

Examples

<.select_group label="Frontend">
  <.select_option value="react" label="React" />
  <.select_option value="vue" label="Vue" />
</.select_group>

Attributes

label (:string) (required) - The group label.
class (:string) - Additional CSS classes. Defaults to nil.
Global attributes are accepted. Additional HTML attributes.

Slots

inner_block (required) - The group options.

select_option(assigns)

Renders a select option.

Examples

<.select_option value="us" label="United States" />
<.select_option value="ca">Canada</.select_option>
<.select_option value="mx" label="Mexico" disabled />

Attributes

value (:string) (required) - The value of this option.
label (:string) - The display label (optional). Defaults to nil.
disabled (:boolean) - Whether this option is disabled. Defaults to false.
class (:string) - Additional CSS classes. Defaults to nil.
Global attributes are accepted. Additional HTML attributes.

Slots

inner_block - The option content.

select_separator(assigns)

Renders a separator between select options or groups.

Examples

<.select_separator />

Attributes

Global attributes are accepted. Additional HTML attributes.

SutraUI.Select (Sutra UI v0.2.0)

Examples

Components

Keyboard Navigation

Form Integration

Colocated Hook

Accessibility

Required ID

Related

Summary

Functions

Functions

select(assigns)

Examples

Attributes

Slots

select_group(assigns)

Examples

Attributes

Slots

select_option(assigns)

Examples

Attributes

Slots

select_separator(assigns)

Examples

Attributes