# `PUI.Select`

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 |

# `map_field`

# `select`

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`

## Attributes

* Global attributes are accepted.

# `select_item`

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)
* `id` (`:string`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `""`.
* `variant` (`:string`) - Defaults to `"default"`. Must be one of `"default"`, or `"unstyled"`.
## Slots

* `inner_block`

# `select_search`

## Attributes

* `listbox_id` (`:string`) - Defaults to `nil`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*