Selector Item
FreeShow a choice as a row with a title and a description, and let a click anywhere on the row toggle its radio, checkbox or switch.
npx wunderui-cli add selector-itemPlayground
Installation
npx wunderui-cli add selector-itemWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
SelectorItem,
SelectorItemGroup,
} from "@/components/wunderui/selector-item"
import type {
SelectorItemGroupProps,
} from "@/components/wunderui/selector-item"Then use it:
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"
export function Delivery() {
return (
<RadioGroup defaultValue="standard" aria-label="Delivery method">
<SelectorItemGroup>
<SelectorItem
title="Standard delivery"
description="3–5 business days"
control={<RadioGroupItem value="standard" />}
/>
<SelectorItem
title="Express delivery"
description="Next business day"
control={<RadioGroupItem value="express" />}
/>
</SelectorItemGroup>
</RadioGroup>
)
}Expected result: You see two bordered rows: Standard delivery with the indigo border and a filled radio, and Express delivery plain. A click anywhere on a row chooses it, and arrow keys move between them.
When to use
Use Selector Item for
- Choices that need a title and an explanation, such as a delivery method or a plan
- A settings row with a switch, a description and an optional action
- A list of people or items to pick from, each with an avatar or an icon
Use something else for
- Checkbox for a short label next to a single box
- Radio Group for a list of plain radios with a label each
- Radio Button Group for one choice from a few short options shown as buttons
- Item Card for a card that opens something instead of choosing it
Control position
A switch sits after the text, a radio or checkbox usually in front. The whole row is one label, so a click anywhere on it toggles the control.
Content
The title names the control for assistive technology. A description adds detail, and a leading icon, avatar or logo helps people find the row at a glance. A default avatar next to a title and a description grows to 44 px, the height of the two lines.
Extras
Metadata is short plain text next to the control, such as a price. An action is a separate button beside the row and never toggles the control, and a helper is a hint under the row.
Orders before 2 pm ship today.
Layout
Card is the bordered row. Inline is a 24 px row without border and padding, for a list inside another surface such as a menu or panel.
States
A chosen radio or checkbox takes the indigo tint with a 1.5 px indigo rim, while a switch only moves its thumb. Point at a row or press Tab to see hover and focus.
Error and invalid
An error turns the row red and shows the message under it. The message is linked to the control, so a screen reader reads it on focus; fix the choice to clear it.
Accept the terms to continue.
Invoices are not available in your country.
Option rows
The selectable card of a form. Put the rows in a SelectorItemGroup with value and onValueChange for a radiogroup (arrow keys choose, one tab stop, an error shows with role alert), or leave the group props out for checkboxes. icon adds the indigo tile, badge a pill next to the title, and href turns the row into a link with a chevron. A chosen card takes the indigo tint with a 1.5 px rim; the text stays neutral. This replaces OptionRow and OptionRowGroup.
Keyboard interactions
A row has one tab stop for its control and one for its action. The keys that change the row are the keys of the control inside it.
- TaborShift+Tab
- Moves focus to the control of the row, then to its action when it has one, and on to the next row. In a radio group only the chosen radio, or the first one when nothing is chosen, is a tab stop.
- ArrowDownorArrowRightorArrowUporArrowLeft
- In a radio group, moves focus to the next or previous row and chooses it. From the last row it wraps to the first. Checkboxes and switches ignore these keys.
- Space
- Toggles the focused checkbox or switch, or chooses the focused radio. A disabled control is skipped.
- Enter
- Toggles the focused switch and presses the focused action. A checkbox and a radio ignore it.
Behavior and motion
What the row does itself, and what it leaves to the page.
- One label
- The leading element, title, description, metadata and control are one label, so a click on any of them toggles the control. The action and the helper or error text sit outside it.
- Names
- Base UI controls are not named by a surrounding label. The row links the title as the name and the description, helper and error as the description, unless the control has its own label.
- Selected
- The row reads the checked state from the control. A chosen radio or checkbox turns the border indigo and the fill subtle, while a switch only moves its thumb, since on is not a selection.
- Hover and pressed
- Hover turns the fill to the page tone, and pressing turns it subtle. A chosen row keeps the subtle fill on hover.
- Helper and error
- Helper text sits under the row in secondary text, and an error turns the row red, marks the control invalid and shows under the row. Announce an error only if it appears after an action.
- Layouts
- The card layout is a bordered row with 16 px vertical and 12 px horizontal padding. The inline layout is a 24 px row without border or padding for menus and panels, and it does not tint on error.
- Disabled
- Disabling the control dims the row to 40 %, shows a not-allowed pointer and stops hover. The action is separate and stays active unless you disable it too.
- Motion
- Border and fill change quickly. Nothing moves, so the row has no layout animation.
- Reduced motion
- With reduced motion the colour changes still fade. Nothing in the row moves, so nothing else changes.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- 1data-slot="selector-item"
The bordered row with 12 px corners, all of it except the action one label, so a click anywhere toggles the control. The row takes the indigo tint and a 1.5 px rim when chosen.
- 2data-slot="selector-item-leading"Optional
An optional icon, avatar or logo before the text. The slot is at least 32 px wide and centres its content, so text starts at the same x in every row.
- data-slot="selector-item-icon"Optional
The prop: a 40 px tile with a tint-indigo fill and the icon in tint-text, with no rim. It sits in the leading slot.
- 3
One line of 14 px medium text. It names the control for assistive technology and is cut with an ellipsis when too long.
- 4Optional
One line of secondary text, 4 px below the title. It describes the control for assistive technology.
- Optional
The prop: a light pill next to the title, such as Recommended.
- 5data-slot="selector-item-metadata"Optional
Short secondary text before the control, such as a price or a count. It sits inside the label and is plain text, not interactive.
- 6data-slot="selector-item-control"
The radio, checkbox or switch you pass as the control. It is the one tab stop of the row and keeps its own focus ring.
- 7data-slot="selector-item-action"Optional
A secondary button such as Edit. It sits outside the label, so clicking it never toggles the control, and it has its own tab stop.
- data-slot="selector-item-description"Optional
- data-slot="selector-item-row"
- data-slot="selector-item-label"Optional
- data-slot="selector-item-helper"Optional
- data-slot="selector-item-error"Optional
- data-slot="selector-item-group"Optional
A vertical stack of rows with an 8 px gap, so several options read as one list.
- data-slot="selector-item-group-error"Optional
The of a radio group: a 14 px red line under the list with , linked to the group.
- data-slot="option-row"Optional
- data-slot="option-row-icon"Optional
- data-slot="option-row-group-field"Optional
- data-slot="option-row-group-error"
Best practices
- Do
Pass the matching control: a radio inside a RadioGroup, or a Checkbox or Switch alone. The border follows the control's checked state, so the row needs no props for it.
- Do
Keep the title to one line and put the detail in the description. Both are truncated, so long text is cut with an ellipsis.
- Do
Put a secondary button in the action slot, not in the title or description. It stays outside the label and has its own tab stop.
- Do
Use the error prop for a row that cannot be chosen or must be ticked. It turns the row red, marks the control invalid and links the message to it.
- Don’t
Don't put a link or button in the title or description. The row is one label, and a click on it toggles the control.
- Don’t
Don't mix controls in one list, such as a switch row between radio rows. People read one control as one kind of choice.
- Don’t
Don't use card rows for a long list. Switch to the inline layout, or to a Select, once there are more than about six options.
API reference
SelectorItem renders the row and the label inside it, and passes no other attributes on, so name the control through the title or its own aria-label. SelectorItemGroup is a plain div.
The bordered row with 12 px corners, all of it except the action one label, so a click anywhere toggles the control. The row takes the indigo tint and a 1.5 px rim when chosen.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | The text that names the control, on one line. It becomes the accessible name of the control and is cut with an ellipsis when it is too long. |
| description | ReactNode | — | A line of detail under the title. It describes the control for assistive technology and is cut with an ellipsis when it is too long. |
| control | ReactNode | — | The control that the row toggles: a inside a , a or a . The row adds , and, with , to it. |
| controlPosition | "leading" | "trailing" | "trailing" | Which side of the text the control sits on. puts it after the text and the metadata, puts it in front of the leading element. |
| leading | ReactNode | — | An icon tile, an avatar or a logo before the text. The slot is at least 32 px wide and centres whatever you pass. |
| metadata | ReactNode | — | Short secondary text before the control, such as a price or a count. It is inside the label and is not interactive. |
| action | ReactNode | — | A secondary control beside the row, such as an Edit button. It is outside the label, so a click on it never toggles the control, and it has its own tab stop. |
| helper | ReactNode | — | A hint under the row. It is linked to the control with . |
| error | ReactNode | — | An error message under the row. It turns the card row red, marks the control and is linked to it with , so a screen reader reads it when the control gets focus. |
| announceError | boolean | — | Reads the error at once with . Set it only for an error that appears after an action, such as a failed submit; leave it off for an error that is there when the page loads. |
| layout | "card" | "inline" | "card" | is the bordered row. is a 24 px row without border and padding. |
| className | string | — | Extra classes for the row that holds the label and the action, merged with its own. Use it for spacing, not to recolour the row. |
| icon | ReactNode | — | An icon in a 40 px tint-indigo tile in front of the text, with no rim. Ignored when is set. |
| badge | ReactNode | — | A small pill next to the title, for example Recommended. |
| badgeColor | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white" | "green" | The colour of the badge. by default. |
| selected | boolean | false | Shows the selected look (indigo tint, 1.5 px tint-text rim) without a checked control, for the current item of a link list. A checked radio or checkbox does it on its own. |
| href | string | — | Link mode: the row is an anchor with a trailing chevron and no control. A or empty href does not jump to the top. |
| onSelect | () => void | — | Link mode: called when the row is pressed. |
A vertical stack of rows with an 8 px gap, so several options read as one list.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The rows to stack. |
| className | string | — | Extra classes, merged with the group's own . Use when the group sits inside a flex row. |
| value | string | — | Radio mode: the chosen value. Setting any group prop turns the group into a radiogroup; without them it stays a plain list. |
| onValueChange | (value) => void | — | Called with the value of the row that was chosen. |
| name | string | — | The name under which the chosen value is submitted with a form. |
| required | boolean | — | A choice is required before the form can be sent. |
| disabled | boolean | — | Disables every row. The arrow keys skip disabled rows. |
| invalid | boolean | — | Marks the group invalid and gives the rows that are not chosen the error tint. Implied by . |
| error | ReactNode | — | An error message under the list. It marks the group invalid, is linked with and is announced with . |
| aria-label | string | — | Names the radiogroup. Give this or . |
| aria-describedby | string | — | Extra description, for example the id of a hint. The error message is added to it. |
| aria-labelledby | string | — | Names the radiogroup by another element, for example a heading. |
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | ReactNode | — | |
| aria-describedby | string | — | Extra description for the control, for example the id of a hint under the row. |
| aria-label | string | — | Names the control (radio, checkbox) or the link when the row has no visible text to name it. |
| aria-labelledby | string | — | Names the control by another element, for a row whose label is somewhere else. |
| badge | ReactNode | — | Small badge next to the title, e.g. "Recommended" |
| badgeColor | "indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative" | "grey" | "black" | "white" | "green" | |
| description | ReactNode | — | |
| disabled | boolean | — | Dims the row once (the row, not its control as well), turns the control or link off and takes it out of the arrow-key order. A disabled disables every row in it. |
| href | string | — | |
| icon | ReactNode | — | Leading icon (rendered in a 40px tint-indigo tile with a tint-text rim for variant="icon") |
| onSelect | () => void | — | |
| selected | boolean | false | |
| value | string | — | Required for radio/checkbox variants — the RadioGroupItem / Checkbox value. |
| variant | "radio" | "checkbox" | "link" | "icon" | "radio" | radio (default) · checkbox · link (chevron, no control) · icon (icon box + trailing radio) |
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | |
| aria-describedby | string | — | Extra description, for example the id of a hint. The error message is added to it. |
| aria-label | string | — | Names the radiogroup. Give this or , or wrap the group in a fieldset with a legend. |
| aria-labelledby | string | — | Names the radiogroup by another element, for example a heading. |
| disabled | boolean | — | Disables every row in the group. Disabled rows are skipped by the arrow keys. |
| error | ReactNode | — | Error message under the list; marks the group invalid and is linked with . Announced when it appears. |
| invalid | boolean | — | Marks the group invalid () and gives the rows that are not chosen the error tint. Implied by . |
| name | string | — | Name of the group in a form: the chosen value is submitted under it (the radios carry hidden inputs). |
| onValueChange | (value) => void | — | |
| required | boolean | — | A choice is required before the form can be submitted (, and native validation on submit). |
| value | string | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("selector-item")npx wunderui-cli add selector-itemThe full library index for assistants is at /llms.txt.