Skip to main content

Choice

A reusable indicator-left, content-right layout for a single choice: a control beside a titled, multi-line label. Put your own checkbox, radio, or switch in Choice.Indicator, and Choice connects it to the title and the description.

When to use

  • Put a checkbox, a radio, or a switch beside an emphasized title and a description.
  • Give a Checkbox or a RadioGroup option a rich, titled label.
  • Build a fully clickable row, such as a list item, with a control beside titled text.
  • Replace a hand-rolled "control + label + helper text" flex layout and its htmlFor and aria-describedby wiring.
  • Prefer Label when the control needs only a one-line caption.
  • Prefer MediaObject, or a plain flex or grid layout, when the thing beside the text is an image or an icon, not a control.
  • Prefer Field.LabelText for a field row with no focusable control, such as a read-only value.

Inside a Field

Drop Choice.Root inside a Field.Control and the field's id / name / aria-invalid and description/error aria-describedby flow onto the control automatically: the field's aria-describedby is merged with the Choice's own description rather than replaced. Because the control adopts the field's id, Choice.Label's htmlFor resolves to that same control, so the title stays a real, clickable label (clicking Email below toggles the checkbox), sharing the control with Field.Label. Reach for Choice.Title only when you specifically want the title to not be a label (e.g. a clickable row that owns the click itself).

Choice.Label vs Choice.Title

Both render the emphasized title with identical typography; they differ in who labels the control:

  • Choice.Label renders a real <label htmlFor>: the title is the control's accessible name, and clicking it toggles the control. Use it for a standalone control (no Field.Label, no clickable row).
  • Choice.Title renders label-less text (a <p>): use it when an ancestor already owns the labeling and click target, such as a fully-clickable row or a Headless radio item. This avoids nesting two <label>s or splitting the click target. (Inside a Field you usually still want Choice.Label, since it merges with the field's id and stays clickable.)

The example below is a fully-clickable row: the row's own <label> (sharing the control's id) owns the click, so the title is a Choice.Title.

Composition

Choice.Root├── Choice.Indicator└── Choice.Content    ├── Choice.Label        (or Choice.Title, pick one)    └── Choice.Description

Polymorphism

Choice.Content, Choice.Title, and Choice.Description each accept asChild to render as your own element while keeping the styling and wiring. For example, render the description as a <div> so it can contain block content. Choice.Label is the mantle Label (it always renders a real <label>, like Field.Label); reach for Choice.Title (which accepts asChild) when you need a different element. Choice.Indicator is itself a slot: it clones whatever single control element you place inside it, injecting the shared id / name / aria-* / disabled.

Layout and association

Choice is a layout and association primitive. It owns the control's id and the description's id and connects them. It does not own the control's value: you put your own control in Choice.Indicator. Use Choice.Label (a real <label>) when the Choice owns the labeling. Use Choice.Title (text with no label) when an ancestor already owns it.

Accessibility

  • The control placed in Choice.Indicator receives the generated id; Choice.Label's htmlFor and the description's aria-describedby resolve to it without manual wiring.
  • Choice.Description associates via aria-describedby only; it is never a second label. A click on it forwards to Choice.Label, so the whole content column toggles the control while the accessible name stays the label alone.
  • Use exactly one of Choice.Label / Choice.Title per choice. Choice.Title is label-less text for when an ancestor (clickable row, radio item, or Field.Label) carries the accessible name, so labels never nest.
  • Inside a RadioGroup item, Choice.Title and Choice.Description register their ids with the radio. The option's aria-labelledby names it by the title alone, and its aria-describedby points at the description.
  • Inside a Field, the control adopts the field's id and its aria-describedby is merged (never duplicated) with the field's description and error ids.

API Reference

Choice.Root

The layout and id/association owner. Renders a <div>. When composed inside a Field.Control, the field's id / name / aria-* take precedence over these props.

All props from div (except id, typed below), plus:

PropTypeDefaultDescription
disabled?booleanfalseMarks the choice disabled: dims the title/description and is injected onto the control.
id?stringExplicit control id. Defaults to a generated id, or the surrounding Field's id when composed in one.
name?stringForm value name injected onto the control. Inherited from Field when composed within one.

Choice.Indicator

The left control slot. Renders a one-line-tall (h-lh) <span> and clones its single element child with the shared id / name / aria-describedby / aria-invalid / aria-errormessage / disabled.

All props from span.

Choice.Content

The right column that stacks the title over the description. Renders a <div>.

All props from div, plus:

PropTypeDefaultDescription
asChild?booleanfalseRender the content column as your own element instead of a <div>.

Choice.Label

The title as a real <label htmlFor> wired to the control. Use when the Choice owns the labeling. This is the mantle Label (not a re-implementation), so it keeps all of its styling and behavior. Field.Label reuses Label the same way.

All props from Label / label, except htmlFor and disabled. Choice.Root owns those (the control id and the choice's disabled state).

Choice.Title

The title as label-less text. Renders a <p>. Use when an ancestor (clickable row, radio item, or Field.Label) owns the control's labeling. Inside a RadioGroup item, it names the radio through aria-labelledby; the id defaults to a generated one.

All props from p, plus:

PropTypeDefaultDescription
asChild?booleanfalseRender the title as your own element instead of a <p>.

Choice.Description

The supplementary description, wired to the control via aria-describedby. Renders a <p>. A click on it forwards to the sibling Choice.Label, so the description extends the label's click target. The forward skips a click on a link or other interactive content inside the description. After it forwards, it marks the click handled with preventDefault(), so a click-to-activate ancestor (a SelectableList row) does not toggle the control a second time. When the choice uses Choice.Title, the description forwards nothing, because an ancestor owns that click. Inside a RadioGroup item, it describes the radio through aria-describedby.

All props from p except id, which Choice.Root owns so the control's aria-describedby always resolves, plus:

PropTypeDefaultDescription
asChild?booleanfalseRender the description as your own element instead of a <p>.