PUI.Select (pui v1.0.0-alpha.27)

A customizable select dropdown with search, grouping, and form-aware errors.

Basic Usage

<.select id="food" name="food">
  <.select_item value="apple">Apple</.select_item>
  <.select_item value="banana">Banana</.select_item>
  <.select_item value="orange">Orange</.select_item>
</.select>

With Options List

Pass options as a list for automatic rendering:

<.select id="food" name="food" options={["Apple", "Banana", "Orange"]} />

With Value/Label Pairs

<.select id="food" name="food" options={[
  {"apple", "Apple"},
  {"banana", "Banana"}
]} />

With Groups

<.select id="food" name="food" options={[
  {"Fruits", ["Apple", "Banana"]},
  {"Vegetables", [{"carrot", "Carrot"}]}
]} />

Searchable Select

<.select id="food" name="food" searchable={true} options={["Option 1", "Option 2"]} />

With Label

<.select id="food" name="food" label="Select Food">
  <:option value="apple">Apple</:option>
</.select>

With Phoenix Form

<.form for={@form}>
  <.select field={@form[:category]} options={@categories} />
</.form>

When field is provided, the component derives id, name, value, and validation errors from the form field and renders those errors below the trigger once the field has been used.

Manual Errors

<.select
  id="category"
  name="category"
  label="Category"
  errors={["Please choose a category."]}
  options={["Design", "Engineering", "Marketing"]}
/>

With Icons

<.select id="food" name="food">
  <.select_item value="apple">
    <.icon name="hero-apple" class="size-4" /> Apple
  </.select_item>
</.select>

With Footer

Add custom content at the bottom of the dropdown, such as action buttons:

<.select id="items" name="items" searchable={true}>
  <.select_item value="item-1">Item One</.select_item>
  <.select_item value="item-2">Item Two</.select_item>
  <:footer>
    <div class="border-t border-border p-2">
      <button type="button" phx-click="add-new" class="text-sm text-primary">
        + Add New Item
      </button>
    </div>
  </:footer>
</.select>

Attributes (select/1)

Attribute	Type	Default	Description
`id`	`string`	`nil`	Unique identifier
`name`	`string`	`nil`	Form field name
`value`	`string`	`nil`	Selected value
`placeholder`	`string`	`"Select an item"`	Placeholder text
`options`	`list`	`[]`	List of options (strings, tuples, or groups)
`searchable`	`boolean`	`false`	Enable search/filter functionality
`class`	`string`	`"w-fit"`	Additional CSS classes
`label`	`string`	`nil`	Label text
`field`	`FormField`	`nil`	Phoenix form field struct
`errors`	`list`	`[]`	Error messages shown below the select

Slots

Slot	Description
`inner_block`	Custom select items using `<.select_item>`
`header`	Content to display at the top of dropdown
`footer`	Content to display at the bottom of dropdown

Summary

Functions

map_field(assigns)

select(assigns)

Renders the select trigger and option list.

select_icon(assigns)

select_item(assigns)

Renders a custom option inside select/1.

select_search(assigns)

Functions

map_field(assigns)

select(assigns)

Renders the select trigger and option list.

Use options for the common tuple/string-based API, or provide custom select_item/1 entries through the default slot. Both manual errors and field-derived validation errors are rendered below the component.

Examples

<.select
  id="food"
  name="food"
  label="Favorite Food"
  options={["Pizza", "Pasta", "Sushi"]}
/>

<.select
  field={@form[:category]}
  label="Category"
  searchable={true}
  options={["Design", "Engineering", "Marketing"]}
/>

<.select
  id="category"
  name="category"
  label="Category"
  errors={["Please choose a category."]}
  options={["Design", "Engineering", "Marketing"]}
/>

Attributes

id (:string) - Defaults to nil.
name (:string) - Defaults to nil.
value (:string) - Defaults to nil.
placeholder (:string) - Defaults to "Select an item".
options (:list) - Defaults to [].
searchable (:boolean) - Defaults to false.
class (:string) - Use w-fit for a width that fits the selected item. Defaults to "w-full".
label (:string) - Defaults to nil.
variant (:string) - Defaults to "default". Must be one of "default", or "unstyled".
field (Phoenix.HTML.FormField) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to nil.
errors (:list) - a list of error strings to display below the select. Defaults to [].
show_errors (:boolean) - Defaults to true.

Slots

inner_block
header
footer

select_icon(assigns)

Attributes

Global attributes are accepted.

select_item(assigns)

Renders a custom option inside select/1.

Examples

<.select_item value="edit">
  <.icon name="hero-pencil" class="size-4" /> Edit
</.select_item>

Attributes

value (:string) (required)
class (:string) - Defaults to "".
variant (:string) - Defaults to "default". Must be one of "default", or "unstyled".