# `PhiaUi.Components.FormSelects`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/components/forms/form_selects.ex#L1)

Selection group components: multi-checkbox groups, card-style radio groups,
cascading selects, and dual-panel transfer lists.

## Components

| Function | Purpose |
|---|---|
| `checkbox_group/1` | Multi-checkbox group with shared label/errors |
| `checkbox_group_item/1` | Single item inside `checkbox_group` |
| `form_checkbox_group/1` | Ecto-integrated checkbox group |
| `radio_card/1` | Single card-style radio option |
| `radio_card_group/1` | Container for `radio_card` items |
| `form_radio_card_group/1` | Ecto-integrated radio card group |
| `cascader/1` | Multi-level cascading select (PhiaCascader hook) |
| `form_cascader/1` | Ecto-integrated cascader |
| `button_transfer_list/1` | Dual-panel item mover (button-based, no DnD) |

# `button_transfer_list`

Renders a dual-panel item mover using `>>` / `>` / `<` / `<<` arrow buttons.

No drag-and-drop required — simpler than `drag_transfer_list`. Moves are triggered
by `phx-click` events that your LiveView handles to update the two item lists.

## Example

    <.button_transfer_list
      id="permissions"
      source_items={@available_permissions}
      target_items={@granted_permissions}
      source_label="Available permissions"
      target_label="Granted permissions"
    />

## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `source_items` (`:list`) - List of {label, value} tuples in the source panel. Defaults to `[]`.
* `target_items` (`:list`) - List of {label, value} tuples in the target panel. Defaults to `[]`.
* `source_label` (`:string`) - Defaults to `"Available"`.
* `target_label` (`:string`) - Defaults to `"Selected"`.
* `class` (`:string`) - Defaults to `nil`.

# `cascader`

Renders a multi-level cascading select powered by the `PhiaCascader` JS hook.

Options are passed as JSON via `data-options`. The hook builds drill-down panels
client-side. Sends `cascader-select` push events with `{level, value}` on each pick.

## Example

    <.cascader
      id="category"
      name="category"
      options={[
        {"Electronics", "electronics", [
          {"Phones", "phones", []},
          {"Laptops", "laptops", []}
        ]},
        {"Clothing", "clothing", []}
      ]}
      value={@selected_path}
    />

## Attributes

* `id` (`:string`) (required) - Required for phx-hook.
* `name` (`:string`) - Hidden input name for form submission. Defaults to `nil`.
* `options` (`:list`) - List of {label, value} or {label, value, children} tuples. Defaults to `[]`.
* `value` (`:list`) - Current selection path as list of string values. Defaults to `[]`.
* `placeholder` (`:string`) - Defaults to `"Select..."`.
* `class` (`:string`) - Defaults to `nil`.

# `checkbox_group`

Renders an accessible multi-checkbox group using `<fieldset>/<legend>`.

## Example

    <.checkbox_group label="Interests" orientation="horizontal">
      <.checkbox_group_item name="interests[]" value="elixir" label="Elixir" checked={true} />
      <.checkbox_group_item name="interests[]" value="rust" label="Rust" />
    </.checkbox_group>

## Attributes

* `label` (`:string`) - Group legend text. Defaults to `nil`.
* `description` (`:string`) - Helper text below the legend. Defaults to `nil`.
* `errors` (`:list`) - List of pre-translated error strings. Defaults to `[]`.
* `orientation` (`:string`) - vertical | horizontal. Defaults to `"vertical"`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block` (required)

# `checkbox_group_item`

Renders a single checkbox option for use inside `checkbox_group/1`.

## Attributes

* `value` (`:string`) (required) - Value submitted when checked.
* `label` (`:string`) (required) - Label text next to the checkbox.
* `checked` (`:boolean`) - Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `name` (`:string`) - Input name — use `name[]` for multi-value. Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-click", "form"]`.

# `form_cascader`

Renders a cascader integrated with `Phoenix.HTML.FormField`.

## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `options` (`:list`) - Defaults to `[]`.
* `placeholder` (`:string`) - Defaults to `"Select..."`.
* `class` (`:string`) - Defaults to `nil`.

# `form_checkbox_group`

Renders a checkbox group integrated with `Phoenix.HTML.FormField`.

The checked state of each item is derived by checking whether its value is
included in `field.value` (which should be a list of selected values).

## Example

    <.form_checkbox_group
      field={@form[:roles]}
      label="Roles"
      options={[{"Admin", "admin"}, {"Editor", "editor"}, {"Viewer", "viewer"}]}
    />

## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `description` (`:string`) - Defaults to `nil`.
* `options` (`:list`) - List of {label, value} tuples. Defaults to `[]`.
* `orientation` (`:string`) - Defaults to `"vertical"`.
* `class` (`:string`) - Defaults to `nil`.

# `form_radio_card_group`

Renders a radio card group integrated with `Phoenix.HTML.FormField`.

## Attributes

* `field` (`Phoenix.HTML.FormField`) (required)
* `label` (`:string`) - Defaults to `nil`.
* `options` (`:list`) (required) - List of {label, value} tuples or %{label:, value:, description:} maps.
* `cols` (`:integer`) - Defaults to `2`.
* `layout` (`:string`) - Defaults to `"stack"`.
* `class` (`:string`) - Defaults to `nil`.

# `radio_card`

Renders a card-style radio option with a hidden native `<input type="radio">`.

Uses CSS `peer` + `peer-checked:*` classes for the selected border ring — no JS required.
The ring overlay and check indicator are direct siblings of the hidden input to satisfy
the CSS `~` sibling selector constraint.

## Example

    <.radio_card_group name="plan" value={@selected_plan}>
      <.radio_card name="plan" value="free" label="Free" description="Up to 5 projects" />
      <.radio_card name="plan" value="pro" label="Pro" description="Unlimited projects" />
    </.radio_card_group>

## Attributes

* `value` (`:string`) (required) - Radio input value.
* `label` (`:string`) (required) - Card heading text.
* `description` (`:string`) - Optional card description. Defaults to `nil`.
* `checked` (`:boolean`) - Whether this card is the selected option. Defaults to `false`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `name` (`:string`) - Radio input name — all cards in a group share one name. Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["phx-change", "phx-click", "form"]`.
## Slots

* `icon` - Optional leading icon slot.

# `radio_card_group`

Renders a container for `radio_card/1` items with accessible `role="radiogroup"`.

Use `layout="grid"` with `cols` for a multi-column card layout.

## Attributes

* `name` (`:string`) (required) - Shared radio input name for all cards in the group.
* `value` (`:string`) - Currently selected value (used to set checked state). Defaults to `nil`.
* `orientation` (`:string`) - vertical | horizontal (for stack layout). Defaults to `"vertical"`.
* `cols` (`:integer`) - Grid columns when layout is 'grid' (2–4). Defaults to `2`.
* `layout` (`:string`) - stack | grid. Defaults to `"stack"`.
* `class` (`:string`) - Defaults to `nil`.
## Slots

* `inner_block` (required)

---

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