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

Advanced select components for PhiaUI.

Provides three higher-level selection patterns beyond the native `<select>`:

- `tree_select/1` + `tree_select_option/1` — hierarchical dropdown with
  expand/collapse via the `PhiaTreeSelect` JS hook.
- `rich_select/1` + `rich_select_option/1` — visible option list where each
  option has an avatar/icon, title, and optional description. Pure HEEx.
- `visual_select/1` + `visual_select_item/1` — grid of image/icon tiles backed
  by radio inputs. Pure HEEx.

# `rich_select`

Renders a visible list of rich radio options — each with avatar/icon + title + description.
Pure HEEx, no JS required. Use `phx-click` or wrap in a Phoenix form for submission.

## Attributes

* `id` (`:string`) - HTML id for the fieldset. Defaults to `nil`.
* `value` (`:string`) - Currently selected option value. Defaults to `nil`.
* `name` (`:string`) - Name attribute for the hidden radio inputs. Defaults to `"rich_select"`.
* `on_change` (`:string`) - LiveView event name fired via `phx-click` when an option is selected. Defaults to `nil`.
* `placeholder` (`:string`) - Optional prompt text shown above the options list (aria-label fallback). Defaults to `nil`.
* `options` (`:list`) - List of option maps. Supported keys:
  - `:value` (required) — option value string
  - `:label` (required) — display title
  - `:description` — optional subtitle text
  - `:icon` — Lucide icon name string
  - `:avatar_src` — URL for an avatar image

  Defaults to `[]`.
* `size` (`:atom`) - Controls option row height and text size. Defaults to `:default`. Must be one of `:sm`, `:default`, or `:lg`.
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.

# `rich_select_option`

Standalone rich select option row — for composable usage outside `rich_select/1`.

## Attributes

* `value` (`:string`) (required) - Option value.
* `label` (`:string`) (required) - Display title.
* `description` (`:string`) - Optional subtitle text. Defaults to `nil`.
* `icon` (`:string`) - Lucide icon name. Defaults to `nil`.
* `avatar_src` (`:string`) - Avatar image URL. Defaults to `nil`.
* `selected` (`:boolean`) - Whether this option is currently selected. Defaults to `false`.
* `name` (`:string`) - Radio input name. Defaults to `"rich_select"`.
* `on_change` (`:string`) - LiveView event name. Defaults to `nil`.
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.

# `tree_select`

Renders a hierarchical tree-select dropdown.

The trigger button opens a popover panel. Nodes with children show an expand
toggle. Selecting a leaf fires `on_change` via the `PhiaTreeSelect` JS hook.
The tree structure is passed via `data-options` (JSON) and rendered client-side.
A hidden `<input>` carries the selected value for form submission.

## Attributes

* `id` (`:string`) (required) - Unique ID — required for PhiaTreeSelect hook.
* `value` (`:string`) - Currently selected node value. Defaults to `nil`.
* `placeholder` (`:string`) - Text shown when no value is selected. Defaults to `"Select…"`.
* `options` (`:list`) - Nested option list. Each map: `%{label: String, value: String, children: [...]}`.
  Children are optional.

  Defaults to `[]`.
* `on_change` (`:string`) - LiveView event name fired when a node is selected. Defaults to `nil`.
* `disabled` (`:boolean`) - Disables the trigger. Defaults to `false`.
* `class` (`:string`) - Additional CSS classes on the root element. Defaults to `nil`.

# `tree_select_option`

Renders a single tree node: expand toggle (if children) + clickable label.
Children are rendered recursively, initially hidden (managed by JS hook).

## Attributes

* `option` (`:map`) (required) - Option map: `%{label, value, children: [...]}`.
* `selected_value` (`:string`) - Currently selected value. Defaults to `nil`.
* `level` (`:integer`) - Nesting depth (0 = root). Defaults to `0`.
* `id_prefix` (`:string`) - ID prefix for expand toggles. Defaults to `"ts"`.

# `visual_select`

Renders a grid of visual radio-backed option tiles.
Each tile can display an image, an icon, a label, and a description.
Pure HEEx — no JS required.

## Attributes

* `id` (`:string`) - HTML id for the fieldset. Defaults to `nil`.
* `name` (`:string`) (required) - Name attribute for the radio inputs.
* `value` (`:string`) - Currently selected option value. Defaults to `nil`.
* `cols` (`:integer`) - Number of grid columns (2, 3, or 4). Defaults to `3`.
* `options` (`:list`) - List of option maps. Supported keys:
  - `:value` (required)
  - `:label` — display text below the tile
  - `:icon` — Lucide icon name (shown if no image)
  - `:image_src` — image URL for the tile thumbnail
  - `:description` — small descriptive text

  Defaults to `[]`.
* `class` (`:string`) - Additional CSS classes on the grid container. Defaults to `nil`.

# `visual_select_item`

Standalone visual select tile — for composable usage outside `visual_select/1`.

## Attributes

* `value` (`:string`) (required) - Option value.
* `label` (`:string`) - Display label below the tile. Defaults to `nil`.
* `image_src` (`:string`) - Thumbnail image URL. Defaults to `nil`.
* `description` (`:string`) - Small descriptive text. Defaults to `nil`.
* `selected` (`:boolean`) - Whether this item is currently selected. Defaults to `false`.
* `name` (`:string`) - Radio input name. Defaults to `"visual_select"`.
* `class` (`:string`) - Additional CSS classes. Defaults to `nil`.

---

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