Radio

An easily stylable radio button component.

Best apple

FujiGalaGranny Smith

'use client';
import * as React from 'react';
import { Radio } from '@base-ui/react/radio';
import { RadioGroup } from '@base-ui/react/radio-group';
import styles from './index.module.css';

export default function ExampleRadioGroup() {
  const id = React.useId();
  return (
    <RadioGroup aria-labelledby={id} defaultValue="fuji-apple" className={styles.RadioGroup}>
      <div className={styles.Caption} id={id}>
        Best apple
      </div>

      <label className={styles.Item}>
        <Radio.Root value="fuji-apple" className={styles.Radio}>
          <Radio.Indicator className={styles.Indicator} />
        </Radio.Root>
        Fuji
      </label>

      <label className={styles.Item}>
        <Radio.Root value="gala-apple" className={styles.Radio}>
          <Radio.Indicator className={styles.Indicator} />
        </Radio.Root>
        Gala
      </label>

      <label className={styles.Item}>
        <Radio.Root value="granny-smith-apple" className={styles.Radio}>
          <Radio.Indicator className={styles.Indicator} />
        </Radio.Root>
        Granny Smith
      </label>
    </RadioGroup>
  );
}

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

A visible label for the group is created by specifying aria-labelledby on <RadioGroup> to reference the id of a sibling element that contains the group label text.

Using aria-labelledby to label a radio group

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

For individual radio buttons, use an enclosing <label> element that wraps each <Radio.Root>. An enclosing label is announced to screen readers when focus is on the control, and ensures that clicking on any gaps between the label and radio still toggles it.

Using an enclosing label to label a radio button

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

The Field and Fieldset components eliminate the need to track id or aria-labelledby associations manually. They support both enclosing and sibling labeling patterns, along with a UX improvement to prevent double clicks from selecting the label text.

Group label: Since the group contains multiple controls, it can be labeled as a fieldset. Use Fieldset by replacing the <Fieldset.Root> element with <RadioGroup> via the render prop. <Fieldset.Legend> provides the visible label for the group.
Individual label: Label an individual radio using an enclosing <Field.Label>. Enclosing labels ensure that clicking on any gaps between the label and radio still toggles it.

Using Field and Fieldset to label a radio group

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

Form integration

To use a radio group in a form, pass the radio group’s name to <Field.Root>:

Using Radio Group in a form

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

API reference

RadioGroup

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

namestring—

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

defaultValueany—

Name: defaultValue
Description: The uncontrolled value of the radio button that should be initially selected.

To render a controlled radio group, use the value prop instead.
Type: any

valueany—

Name: value
Description: The controlled value of the radio item that should be currently selected.

To render an uncontrolled radio group, use the defaultValue prop instead.
Type: any

onValueChangefunction—

Name: onValueChange
Description: Callback fired when the value changes.
Type: | (( value: any, eventDetails: Radio.Group.ChangeEventDetails, ) => void) | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

readOnlybooleanfalse

Name: readOnly
Description: Whether the user should be unable to select a different radio button in the group.
Type: boolean | undefined
Default: false

requiredbooleanfalse

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean | undefined
Default: false

inputRefRef<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden input element.
Type: React.Ref<HTMLInputElement> | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: RadioGroup.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | ((state: RadioGroup.State) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: RadioGroup.State, ) => ReactElement)

data-disabled

Present when the radio group is disabled.

Attribute	Description	-
`data-disabled`	Present when the radio group is disabled.

Root

Represents the radio button itself. Renders a <span> element and a hidden <input> beside.

value^*any—

Name: value
Description: The unique identifying value of the radio in a group.
Type: any

nativeButtonbooleanfalse

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
Type: boolean | undefined
Default: false

disabledboolean—

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined

readOnlyboolean—

Name: readOnly
Description: Whether the user should be unable to select the radio button.
Type: boolean | undefined

requiredboolean—

Name: required
Description: Whether the user must choose a value before submitting a form.
Type: boolean | undefined

inputRefRef<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden input element.
Type: React.Ref<HTMLInputElement> | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Radio.Root.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | ((state: Radio.Root.State) => CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Radio.Root.State, ) => ReactElement)

data-checked

Present when the radio is checked.

data-unchecked

Present when the radio is not checked.

data-disabled

Present when the radio is disabled.

data-readonly

Present when the radio is readonly.

data-required

Present when the radio is required.

data-valid

Present when the radio is in valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the radio's value has changed (when wrapped in Field.Root).

data-touched

Present when the radio has been touched (when wrapped in Field.Root).

data-filled

Present when the radio is checked (when wrapped in Field.Root).

data-focused

Present when the radio is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-checked`	Present when the radio is checked.
`data-unchecked`	Present when the radio is not checked.
`data-disabled`	Present when the radio is disabled.
`data-readonly`	Present when the radio is readonly.
`data-required`	Present when the radio is required.
`data-valid`	Present when the radio is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the radio's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the radio has been touched (when wrapped in Field.Root).
`data-filled`	Present when the radio is checked (when wrapped in Field.Root).
`data-focused`	Present when the radio is focused (when wrapped in Field.Root).

Indicator

Indicates whether the radio button is selected. Renders a <span> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Radio.Indicator.State) => string | undefined)

styleReact.CSSProperties | function—

Name: style
Type: | React.CSSProperties | (( state: Radio.Indicator.State, ) => CSSProperties | undefined) | undefined

keepMountedbooleanfalse

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

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Radio.Indicator.State, ) => ReactElement)

data-checked

Present when the radio is checked.

data-unchecked

Present when the radio is not checked.

data-disabled

Present when the radio is disabled.

data-readonly

Present when the radio is readonly.

data-required

Present when the radio is required.

data-valid

Present when the radio is in valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in invalid state (when wrapped in Field.Root).

data-dirty

Present when the radio's value has changed (when wrapped in Field.Root).

data-touched

Present when the radio has been touched (when wrapped in Field.Root).

data-filled

Present when the radio is checked (when wrapped in Field.Root).

data-focused

Present when the radio is focused (when wrapped in Field.Root).

Attribute	Description	-
`data-checked`	Present when the radio is checked.
`data-unchecked`	Present when the radio is not checked.
`data-disabled`	Present when the radio is disabled.
`data-readonly`	Present when the radio is readonly.
`data-required`	Present when the radio is required.
`data-valid`	Present when the radio is in valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in invalid state (when wrapped in Field.Root).
`data-dirty`	Present when the radio's value has changed (when wrapped in Field.Root).
`data-touched`	Present when the radio has been touched (when wrapped in Field.Root).
`data-filled`	Present when the radio is checked (when wrapped in Field.Root).
`data-focused`	Present when the radio is focused (when wrapped in Field.Root).