Radio

01Preview

Change the controls to try every supported combination. The preview is a real, controlled RadioGroup: choose an option and the value control follows, and the code updates with it.

import { Radio, RadioGroup } from '@nuton/ui'

const [value, setValue] = useState('space')

<RadioGroup label="Who can see this lesson?" value={value} onValueChange={setValue}>
  <Radio value="private" label="Only me" description="Keep the lesson as a draft while you work on it." />
  <Radio value="space" label="Students in this space" description="Everyone enrolled in Biology 101 can open it." />
  <Radio value="link" label="Anyone with the link" description="Share it with students outside the space." />
</RadioGroup>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

Peer dependencies: react and react-dom 18 or later. Add @remixicon/react only if you pass icons into a badge or action (Remix Icon is Nuton's icon set, D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

Labels use --nu-font-body (Inter). Map the token to your loaded font as described on the Button page. Radio's label layout styles ship in the same stylesheet as Checkbox's, so import the whole styles.css rather than picking files.

03Usage

import { Radio, RadioGroup } from '@nuton/ui'

export function LessonVisibility() {
  return (
    <RadioGroup label="Who can see this lesson?" name="visibility" defaultValue="space">
      <Radio value="private" label="Only me" />
      <Radio value="space" label="Students in this space" />
      <Radio value="link" label="Anyone with the link" />
    </RadioGroup>
  )
}

• Always put radios in a RadioGroup. It renders a <fieldset role="radiogroup">, shares one name and gives you native arrow-key movement.
• Control it with value and onValueChange, or leave it uncontrolled with defaultValue. Each Radio needs a value.
• Name the group: label (the legend), a surrounding Field, or aria-label. Development warnings flag a missing group or option name.
• Preselect the safest or most common option, so the group is never empty unless a choice must be deliberate (a quiz answer).
• Keep options short, parallel and in a logical order. Use 2–5 options; for more, use a Select.

04Variants and sizes

Radio has one size. The group sets the orientation; each option can carry the text that Figma's Radio Label defines.

Orientation

<RadioGroup label="Lesson length" defaultValue="15">
  <Radio value="10" label="10 minutes" />
  <Radio value="15" label="15 minutes" />
  <Radio value="30" label="30 minutes" />
</RadioGroup>

<RadioGroup label="Lesson length" orientation="horizontal" defaultValue="15">
  <Radio value="10" label="10 minutes" />
  <Radio value="15" label="15 minutes" />
  <Radio value="30" label="30 minutes" />
</RadioGroup>

Vertical is the default and the easiest to scan. Use horizontal only for two or three short options; it wraps on narrow screens.

Label options

<RadioGroup label="AI tutor feedback" defaultValue="hints">
  <Radio value="hints" label="Hints only" description="The tutor nudges students without giving the answer." />
  <Radio value="worked" label="Worked examples" sublabel="(Recommended)" />
  <Radio
    value="voice"
    label="Spoken feedback"
    badge={<Badge size="sm" color="blue" appearance="light">New</Badge>}
    action={<LinkButton href="/help/spoken-feedback" tone="primary" size="sm">Try a sample</LinkButton>}
  />
  <Radio value="off" label="No feedback" flip />
</RadioGroup>

• sublabel is part of the accessible name; description is linked with aria-describedby.
• badge and action render outside the <label>: not part of the name, and the action is never nested in it.
• flip moves the control to the trailing edge. Use it for every option in a group or none.

Sizes

Values from the component CSS, which follows Figma's geometry (Radio [1.1] 4457:59937, Radio Label [1.1] 4457:59961). Figma has one size and defines no group.

05States and interactions

State tokens

Set on .nu-radio. Override them on a wrapper only for a documented exception.

06Composition examples

Quiz question in a Field

A Field names the group with its label and links its hint and error to the group. Nothing is preselected, because the student must choose. Submit without an answer to see the error and focus move into the group.

<form onSubmit={checkAnswer} noValidate>
  <Field
    label="Which part of the cell releases energy from food?"
    hint="Question 3 of 10"
    error={error}
  >
    <RadioGroup ref={groupRef} value={answer} onValueChange={setAnswer} required>
      <Radio value="nucleus" label="Nucleus" />
      <Radio value="mitochondria" label="Mitochondria" />
      <Radio value="cell-wall" label="Cell wall" />
      <Radio value="ribosome" label="Ribosome" />
    </RadioGroup>
  </Field>
  <Button size="sm" type="submit">Check answer</Button>
</form>

Inside a Field, leave out the group's label: the Field label names it. The group takes invalid, disabled and required from the Field.

Setting with details

Descriptions explain each option. A badge flags something new, and an action under the text opens more detail without selecting the option.

<RadioGroup label="Lesson pace" value={pace} onValueChange={setPace}>
  <Radio value="gentle" label="Gentle" description="Shorter sections with a recap after each one." />
  <Radio value="standard" label="Standard" description="The pace most students in this space choose." />
  <Radio
    value="accelerated"
    label="Accelerated"
    description="Fewer recaps and harder practice questions."
    badge={<Badge size="sm" color="blue" appearance="light">New</Badge>}
    action={
      <LinkButton tone="primary" size="sm" aria-expanded={open} onClick={() => setOpen(!open)}>
        {open ? 'Hide details' : 'How it works'}
      </LinkButton>
    }
  />
</RadioGroup>

In a native form

The radios are native inputs that share the group's name, so an uncontrolled group submits its value with the form and required uses the browser's validation.

// Inside your <form>: submits joining=invite until another option is chosen
<RadioGroup label="Who can join Biology 101?" name="joining" defaultValue="invite" required>
  <Radio value="invite" label="Students with an invite" />
  <Radio value="code" label="Anyone with the class code" />
</RadioGroup>

When to use something else

• More than five options, or little space: a Select.
• Switching a view (list or grid) where the change is immediate: Button group.
• Several options may be true at once: Checkbox.

07API reference

RadioGroup props

Radio props

Styling hooks

The group renders .nu-radio-group (with data-orientation and data-disabled), .nu-radio-group__legend and .nu-radio-group__items. Each control is .nu-radio (with data-invalid and data-disabled); with a label, the layout is .nu-choice with data-kind="radio", shared with Checkbox. Use props rather than styling these; the --nu-radio-*tokens (see State tokens) are the supported override points.

Accessibility

You must: put radios in a named RadioGroup; give every option a visible label (or aria-label); say why the group is invalid in text, such as a Field error, not only with red rings.

The sublabel is spaced from the label with a margin, not a space character. Test environments compute “Worked examples (Recommended)”, but some browsers may join the two words in the accessible name (pending a decision).

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Rendering radios without a RadioGroup and forgetting a shared name, so arrow keys and single selection break.
• Setting checked on a Radio inside a group. The group's value wins; set it there.
• Giving the group a label inside a Field, so it is named twice.
• Selecting an option on hover or focus without the user choosing it, or triggering a page change on selection.

Related components

• CheckboxPick any number of options.
• Inputs and fieldsLabel, hint and error for a radio group, and Select for long lists.
• Button groupA segmented control for switching views.
• Dropdown menuRadio items inside a menu.
• BadgeThe badge passed to a radio label.