# Selector Item

A list row pairing a leading icon/avatar and label/description with a trailing radio, checkbox, or switch.

- Category: Forms
- Page: https://wunderui.com/components/selector-item
- Tier: Free

## Install

```bash
npx wunderui-cli add selector-item
```

## Import

```tsx
import { SelectorItem, OptionRow, OptionRowGroup, SelectorItemGroup, SelectorItemGroupProps } from "@/components/wunderui/selector-item"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <RadioGroup defaultValue="express" aria-label="Delivery method">
      <SelectorItem
        title="Express delivery"
        description="Arrives tomorrow"
        control={<RadioGroupItem value="express" />}
      />
    </RadioGroup>
  )
}
```

## 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

- [Checkbox](https://wunderui.com/components/checkbox) for a short label next to a single box
- [Radio Group](https://wunderui.com/components/radio-group) for a list of plain radios with a label each
- [Radio Button Group](https://wunderui.com/components/radio-button-group) for one choice from a few short options shown as buttons
- [Item Card](https://wunderui.com/components/item-card) for a card that opens something instead of choosing it

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+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. |
| `ArrowDown` or `ArrowRight` or `ArrowUp` or `ArrowLeft` | 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

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

- `SelectorItem`: 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.
- `SelectorItemGroup`: A vertical stack of rows with an 8 px gap, so several options read as one list.
- `Leading`: 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.
- `Icon tile`: The `icon` 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.
- `Title`: One line of 14 px medium text. It names the control for assistive technology and is cut with an ellipsis when too long.
- `Description`: One line of secondary text, 4 px below the title. It describes the control for assistive technology.
- `Badge`: The `badge` prop: a light pill next to the title, such as Recommended.
- `Metadata`: Short secondary text before the control, such as a price or a count. It sits inside the label and is plain text, not interactive.
- `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.
- `Action`: 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.
- `Group error`: The `error` of a radio group: a 14 px red line under the list with `role="alert"`, linked to the group.
- `OptionRow`
- `OptionRowGroup`
- `Description`
- `Row`
- `Label`
- `Helper`
- `Error`
- `Option Row Icon`
- `Option Row Group Error`

## Best practices

### When to use

- Use it for choices needing a title and an explanation: delivery methods, plans, a switch setting. For a short label by a box use Checkbox with Label, for button-sized options Radio Button Group.

### 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.
- Keep the title to one line and put the detail in the description. Both are truncated, so long text is cut with an ellipsis.
- 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.
- 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 mix controls in one list, such as a switch row between radio rows. People read one control as one kind of choice.
- 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

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | 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. |
| 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. |
| announceError | boolean |  | Reads the error at once with `role="alert"`. 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. |
| 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. `green` by default. |
| 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. |
| control | ReactNode |  | The control that the row toggles: a `RadioGroupItem` inside a `RadioGroup`, a `Checkbox` or a `Switch`. The row adds `aria-labelledby`, `aria-describedby` and, with `error`, `aria-invalid` to it. |
| controlPosition | "leading" \| "trailing" | "trailing" | Which side of the text the control sits on. `trailing` puts it after the text and the metadata, `leading` puts it in front of the leading element. |
| 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. |
| error | ReactNode |  | An error message under the row. It turns the card row red, marks the control `aria-invalid` and is linked to it with `aria-describedby`, so a screen reader reads it when the control gets focus. |
| helper | ReactNode |  | A hint under the row. It is linked to the control with `aria-describedby`. |
| 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. |
| icon | ReactNode |  | An icon in a 40 px tint-indigo tile in front of the text, with no rim. Ignored when `leading` is set. |
| layout | "card" \| "inline" | "card" | `card` is the bordered row. `inline` is a 24 px row without border and padding. |
| 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. |
| onSelect | () => void |  | Link mode: called when the row is pressed. |
| 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. |

### OptionRow

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.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 | React.ReactNode |  | Small badge next to the title, e.g. "Recommended" |
| badgeColor | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" \| "grey" \| "black" \| "white" | "green" |  |
| className | string |  |  |
| description | React.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 `OptionRowGroup` disables every row in it. |
| href | string |  |  |
| icon | React.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) |

### OptionRowGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.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 `aria-labelledby`, or wrap the group in a fieldset with a legend. |
| aria-labelledby | string |  | Names the radiogroup by another element, for example a heading. |
| className | string |  |  |
| disabled | boolean |  | Disables every row in the group. Disabled rows are skipped by the arrow keys. |
| error | React.ReactNode |  | Error message under the list; marks the group invalid and is linked with `aria-describedby`. Announced when it appears. |
| invalid | boolean |  | Marks the group invalid (`aria-invalid`) and gives the rows that are not chosen the error tint. Implied by `error`. |
| name | string |  | Name of the group in a form: the chosen value is submitted under it (the radios carry hidden inputs). |
| onValueChange | (value: string) => void |  |  |
| required | boolean |  | A choice is required before the form can be submitted (`aria-required`, and native validation on submit). |
| value | string |  |  |

### SelectorItemGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The rows to stack. |
| 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 `aria-labelledby`. |
| aria-labelledby | string |  | Names the radiogroup by another element, for example a heading. |
| className | string |  | Extra classes, merged with the group's own `flex flex-col gap-2`. Use `min-w-0` when the group sits inside a flex row. |
| disabled | boolean |  | Disables every row. The arrow keys skip disabled rows. |
| error | ReactNode |  | An error message under the list. It marks the group invalid, is linked with `aria-describedby` and is announced with `role="alert"`. |
| invalid | boolean |  | Marks the group invalid and gives the rows that are not chosen the error tint. Implied by `error`. |
| name | string |  | The name under which the chosen value is submitted with a form. |
| onValueChange | (value: string) => void |  | Called with the value of the row that was chosen. |
| required | boolean |  | A choice is required before the form can be sent. |
| value | string |  | Radio mode: the chosen value. Setting any group prop turns the group into a radiogroup; without them it stays a plain list. |

## Examples

### Control position: trailing and leading

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <SelectorItem
      title="Gift wrapping"
      description="Add a card and a ribbon"
      control={<Checkbox defaultChecked />}
    />
  )
}
```

### Content: title, description and icon

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <RadioGroup defaultValue="express" aria-label="Delivery method">
      <SelectorItem
        title="Express delivery"
        control={<RadioGroupItem value="express" />}
      />
    </RadioGroup>
  )
}
```

### Extras: metadata, action and helper

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <RadioGroup defaultValue="express" aria-label="Delivery method">
      <SelectorItem
        title="Express delivery"
        description="Arrives tomorrow"
        metadata="$14"
        control={<RadioGroupItem value="express" />}
      />
    </RadioGroup>
  )
}
```

### Layout: card and inline

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <SelectorItem
      controlPosition="leading"
      title="Gift wrapping"
      description="Add a card and a ribbon"
      control={<Checkbox defaultChecked />}
    />
  )
}
```

### States: rest, selected and disabled

```tsx
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  return (
    <RadioGroup aria-label="Delivery method">
      <SelectorItem
        title="Express delivery"
        description="Arrives tomorrow"
        control={<RadioGroupItem value="express" />}
      />
    </RadioGroup>
  )
}
```

### Error and invalid: the row

```tsx
import { useState } from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { SelectorItem } from "@/components/ui/selector-item"

export function Example() {
  const [accepted, setAccepted] = useState(false)

  return (
    <SelectorItem
      controlPosition="leading"
      title="I accept the terms"
      description="Terms of Service and Privacy Policy"
      error={accepted ? undefined : "Accept the terms to continue."}
      control={<Checkbox checked={accepted} onCheckedChange={setAccepted} />}
    />
  )
}
```

### Option rows: a radio group with icon and badge, checkboxes and links

```tsx
import { useState } from "react"
import { KeyRound, ShieldCheck, Smartphone } from "lucide-react"
import { RadioGroupItem, SelectorItem, SelectorItemGroup } from "@wunderui/react"

export function VerificationMethod() {
  const [method, setMethod] = useState("app")

  return (
    <SelectorItemGroup aria-label="Verification method" value={method} onValueChange={setMethod}>
      <SelectorItem
        icon={<ShieldCheck />}
        title="Authenticator app"
        description="Use a code from an app like 1Password"
        badge="Recommended"
        control={<RadioGroupItem value="app" />}
      />
      <SelectorItem
        icon={<Smartphone />}
        title="Text message"
        description="We send a code to your phone"
        control={<RadioGroupItem value="sms" />}
      />
      <SelectorItem
        icon={<KeyRound />}
        title="Security key"
        description="Use a hardware key or passkey"
        control={<RadioGroupItem value="key" />}
      />
    </SelectorItemGroup>
  )
}
```

## In context

### Shipping method: icon rows with a price

One Selector Item per option, with an icon tile, a description and the price as metadata. The chosen row takes the indigo tint and rim, and the order total follows the choice.

```tsx
import { useState } from "react"
import { Package, Store, Truck } from "lucide-react"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"

const METHODS = [
  { value: "standard", title: "Standard delivery", description: "3–5 business days", price: 0, icon: Truck },
  { value: "express", title: "Express delivery", description: "Next business day", price: 14, icon: Package },
  { value: "pickup", title: "Store pickup", description: "Ready in 2 hours", price: 0, icon: Store },
]

export function Example() {
  const [value, setValue] = useState("standard")
  const method = METHODS.find((item) => item.value === value) ?? METHODS[0]
  const total = 649 + method.price

  return (
    <div className="flex flex-col gap-3">
      <p id="shipping-label" className="text-sm font-medium text-foreground">
        Shipping method
      </p>
      <RadioGroup value={value} onValueChange={setValue} aria-labelledby="shipping-label">
        <SelectorItemGroup>
          {METHODS.map((item) => {
            const Icon = item.icon
            return (
              <SelectorItem
                key={item.value}
                leading={
                  <span aria-hidden className="flex size-8 items-center justify-center rounded-md bg-tint-indigo text-tint-text-indigo [&_svg]:size-4">
                    <Icon />
                  </span>
                }
                title={item.title}
                description={item.description}
                metadata={item.price === 0 ? "Free" : `$${item.price}`}
                control={<RadioGroupItem value={item.value} />}
              />
            )
          })}
        </SelectorItemGroup>
      </RadioGroup>
      <p aria-live="polite" className="flex justify-between text-sm text-text-secondary">
        <span>Order total</span>
        <span className="font-medium text-foreground">${total.toLocaleString("en-US")}</span>
      </p>
    </div>
  )
}
```

### Payment method: a secondary action beside the row

Edit is a separate button outside the label. Pressing it never chooses the card, and it has its own tab stop.

```tsx
import { useState } from "react"
import { CreditCard } from "lucide-react"
import { Button } from "@/components/ui/button"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"

const CARDS = [
  { value: "visa", title: "Visa ending 4242", description: "Expires 08/28" },
  { value: "mastercard", title: "Mastercard ending 1881", description: "Expires 03/27" },
]

export function Example() {
  const [value, setValue] = useState("visa")
  const [editing, setEditing] = useState("")

  return (
    <div className="flex flex-col gap-3">
      <p id="payment-label" className="text-sm font-medium text-foreground">
        Payment method
      </p>
      <RadioGroup value={value} onValueChange={setValue} aria-labelledby="payment-label">
        <SelectorItemGroup>
          {CARDS.map((card) => (
            <SelectorItem
              key={card.value}
              leading={
                <span aria-hidden className="flex size-8 items-center justify-center rounded-md bg-tint-indigo text-tint-text-indigo [&_svg]:size-4">
                  <CreditCard />
                </span>
              }
              title={card.title}
              description={card.description}
              action={
                <Button variant="plain" size="sm" aria-label={`Edit ${card.title}`} onClick={() => setEditing(card.title)}>
                  Edit
                </Button>
              }
              control={<RadioGroupItem value={card.value} />}
            />
          ))}
        </SelectorItemGroup>
      </RadioGroup>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {editing ? `Editing ${editing}.` : ""}
      </p>
    </div>
  )
}
```

### Invite to the project: checkbox rows with avatars

Any number of people can be chosen. The button counts them and turns off when nobody is chosen.

```tsx
import { useState } from "react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { SelectorItem, SelectorItemGroup } from "@/components/ui/selector-item"

const PEOPLE = [
  { id: "nora", name: "Nora Lindgren", role: "Product lead", initials: "NL", color: "indigo" },
  { id: "daniel", name: "Daniel Okafor", role: "Engineering", initials: "DO", color: "purple" },
  { id: "priya", name: "Priya Raman", role: "Billing", initials: "PR", color: "pink" },
] as const

export function Example() {
  const [picked, setPicked] = useState<string[]>(["nora"])
  const [sent, setSent] = useState(false)

  return (
    <div className="flex flex-col gap-3">
      <p id="people-label" className="text-sm font-medium text-foreground">
        Invite to the project
      </p>
      <SelectorItemGroup>
        {PEOPLE.map((person) => (
          <SelectorItem
            key={person.id}
            controlPosition="leading"
            leading={
              <Avatar size="xs" color={person.color} aria-hidden>
                <AvatarFallback>{person.initials}</AvatarFallback>
              </Avatar>
            }
            title={person.name}
            description={person.role}
            control={
              <Checkbox
                checked={picked.includes(person.id)}
                onCheckedChange={(checked) => {
                  setSent(false)
                  setPicked((list) => (checked ? [...list, person.id] : list.filter((id) => id !== person.id)))
                }}
              />
            }
          />
        ))}
      </SelectorItemGroup>
      <Button variant="gradient" disabled={picked.length === 0} onClick={() => setSent(true)}>
        {picked.length === 1 ? "Invite 1 person" : `Invite ${picked.length} people`}
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {sent ? "Invitations sent from info@wunderui.com." : ""}
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("selector-item")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
