组件

Radio Group

Pick exactly one. Each choice is a hand-circled ring; picking it colors the dot in with a terracotta blot and writes a felt spiral into it. Radix Radio Group underneath: roving focus, arrow keys, form value, orientation and direction.

安装

terminal
npx shadcn@latest add @wobko/radio-group

第一次使用?先把 registry 加进 components.json。 如何安装

示例

Default

Pick one. The choice is circled, then colored in: a terracotta blot with a felt spiral written into it. Arrow keys move the choice.

Sizes and states

16, 20 and 28 px; off, on, invalid (red pencil, still red on top of the dot) and disabled (dashed, graphite dot). A horizontal group lays its radios in a row.

Plan picker

Radios with a title and a line of help, and a second horizontal group for billing. Hovering the row lights its radio; the description hangs off the label with aria-describedby.

In a form

`name` on the group puts the chosen value in FormData (Radix keeps hidden native radios in sync) and `required` blocks the submit until one is picked.

Demo

Official `radio-group-demo`: three options, the middle one chosen. Click, or focus the group and use the arrow keys; the chosen ring gets its dot written in. Only change: the ids are prefixed to stay unique on a page with other examples.

API 参考

RadioGroup

The root (Radix RadioGroup, role=radiogroup): a grid with a gap; `orientation="horizontal"` lays it out as a wrapping row.

属性类型默认值说明
value / defaultValue / onValueChangestring / string / (value: string) => void-Controlled or uncontrolled selection.
name / required / disabled / formstring | boolean-Forwarded to Radix's hidden native radios, so the value is in FormData and `required` blocks the submit. A form reset puts the group back to its `defaultValue`. `disabled` on the group draws every radio disabled.
aria-invalidboolean | "true" | "false"-On the group (where FormControl puts it) every radio is drawn in red pencil; a radio can still set its own aria-invalid.
orientation"horizontal" | "vertical"-Arrow-key axis (and, here, the layout). Radix arrows work on both axes either way.
dir"ltr" | "rtl"-Direction for the arrow keys.
loopbooleantrueArrow keys wrap around.

RadioGroupItem

Radix RadioGroup.Item (a <button role="radio">, plus a hidden input inside a form) with the ring drawn behind it. Size it with size-*: 16, 20 and 28 px are drawn and tested. The spiral is written with ll-draw when the state turns checked after a touch (instantly with reduced motion; never at load).

属性类型默认值说明
valuestring-The value the group takes when this radio is chosen.
disabledbooleanfalseDashed pencil ring on a graphite wash, graphite dot when chosen. Not focusable.
aria-invalidboolean | "true" | "false"-true draws the ring in red pencil, and keeps it red over the dot.
seedstring | number-Pins the hand: the same seed always draws the same ring and dot. Default: derived from useId().

无障碍

  • role="radiogroup" with role="radio" items and aria-checked. Tab enters the group at the chosen radio (or the first), arrow keys move AND choose, Space chooses the focused radio (Radix roving focus). Give the group a name with aria-label or aria-labelledby (a fieldset legend works too).
  • Label each radio with <Label htmlFor>, wrap it, or use aria-label. A Label beside it is a peer: peer-disabled dims it, and hovering the row (a `group/field`) or the label right after the radio lights the ring's hover overlay.
  • The hit area reaches 8 px past the ring on every side (an ::after, so layout never moves): 32 px for the 16 px ring.
  • Keyboard focus draws a blue felt ring; the drawing is aria-hidden, pointer-events: none and never focusable. Windows high contrast replaces it by a real border and the Indicator shows a real dot.
  • The chosen state is a filled dot, not only a color: a bold blot with a dark spiral. Reduced motion shows the finished dot at once.
  • Right-to-left needs nothing: the ring is symmetric and every offset is logical. Pass `dir="rtl"` to mirror the arrow keys.

源码

CLI 会复制进你项目的文件。

正在加载源码