Radio

An easily stylable radio button component.

Best apple

FujiGalaGranny Smith

Usage guidelines

Form controls must have an accessible name: It can be created using <label> elements, or the Field and Fieldset components. See Labeling a radio group and the forms guide.

Anatomy

Radio is always placed within Radio Group. Import the components and place them together:

Anatomy

import { Radio } from '@base-ui/react/radio';
import { RadioGroup } from '@base-ui/react/radio-group';

<RadioGroup>
  <Radio.Root>
    <Radio.Indicator />
  </Radio.Root>
</RadioGroup>;

Examples

Labeling a radio group

Label the group with aria-labelledby and a sibling label element:

Using aria-labelledby to label a radio group

<div id="storage-type-label">Storage type</div>
<RadioGroup aria-labelledby="storage-type-label">{/* ... */}</RadioGroup>

An enclosing <label> is the simplest labeling pattern for each radio:

Using an enclosing label to label a radio button

<label>
  <Radio.Root value="ssd" />
  SSD
</label>

Rendering as a native button

By default, <Radio.Root> renders a <span> element to support enclosing labels. Prefer rendering each radio as a native button when using sibling labels (htmlFor/id).

Sibling label pattern with a native button

<div id="storage-type">Storage type</div>
<RadioGroup defaultValue="ssd" aria-labelledby="storage-type">
  <div>
    <label htmlFor="storage-type-ssd">SSD</label>
    <Radio.Root value="ssd" id="storage-type-ssd" nativeButton render={<button />}>
      <Radio.Indicator />
    </Radio.Root>
  </div>
</RadioGroup>

Native buttons with wrapping labels are supported by using the render callback to avoid invalid HTML, so the hidden input is placed outside the label:

Render callback

<div id="storage-type">Storage type</div>
<RadioGroup defaultValue="ssd" aria-labelledby="storage-type">
  <Radio.Root
    value="ssd"
    nativeButton
    render={(buttonProps) => (
      <label>
        <button {...buttonProps} />
        SSD
      </label>
    )}
  />
</RadioGroup>

Form integration

Use Field and Fieldset for group labeling and form integration:

Using Radio Group in a form

<Form>
  <Field.Root name="storageType">
    <Fieldset.Root render={<RadioGroup />}>
      <Fieldset.Legend>Storage type</Fieldset.Legend>
      <Field.Item>
        <Field.Label>
          <Radio.Root value="ssd" />
          SSD
        </Field.Label>
      </Field.Item>
      <Field.Item>
        <Field.Label>
          <Radio.Root value="hdd" />
          HDD
        </Field.Label>
      </Field.Item>
    </Fieldset.Root>
  </Field.Root>
</Form>

API reference

RadioGroup

Provides a shared state to a series of radio buttons. Renders a <div> element.

Root

Name	Type	Default	Description
`disabled`Optional	`boolean \| undefined`	`false`	Whether the component should ignore user interaction.
`readOnly`Optional	`boolean \| undefined`	`false`	Whether the user should be unable to select a different radio button in the group.
`required`Optional	`boolean \| undefined`	`false`	Whether the user must choose a value before submitting a form.
`name`Optional	`string \| undefined`	—	Identifies the field when a form is submitted.
`value`Optional	`Value \| undefined`	—	The controlled value of the radio item that should be currently selected. To render an uncontrolled radio group, use the `defaultValue` prop instead.
`defaultValue`Optional	`Value \| undefined`	—	The uncontrolled value of the radio button that should be initially selected. To render a controlled radio group, use the `value` prop instead.
`onValueChange`Optional	`((value: Value, eventDetails: RadioGroup.ChangeEventDetails) => void) \| undefined`	—	Callback fired when the value changes.
`inputRef`Optional	`React.Ref<HTMLInputElement> \| undefined`	—	A ref to access the hidden input element.

Root

Name	Type	Default	Description
`value`Required	`Value`	—	The unique identifying value of the radio in a group.
`disabled`Optional	`boolean \| undefined`	—	Whether the component should ignore user interaction.
`required`Optional	`boolean \| undefined`	—	Whether the user must choose a value before submitting a form.
`readOnly`Optional	`boolean \| undefined`	—	Whether the user should be unable to select the radio button.
`inputRef`Optional	`React.Ref<HTMLInputElement> \| undefined`	—	A ref to access the hidden input element.

Indicator

Name	Type	Default	Description
`keepMounted`Optional	`boolean \| undefined`	`false`	Whether to keep the HTML element in the DOM when the radio button is inactive.

Radio

Root

Root

Indicator

On this page