Radio

An easily stylable radio button component.

Best apple

FujiGalaGranny Smith

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

export default function ExampleRadioGroup() {
  return (
    <RadioGroup
      aria-labelledby="apples-caption"
      defaultValue="fuji-apple"
      className={styles.RadioGroup}
    >
      <div className={styles.Caption} id="apples-caption">
        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>
  );
}

Anatomy

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

Anatomy

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

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

API reference

RadioGroup

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

Prop	Type	Default
`name`	`string`	`undefined`
`defaultValue`	`any`	`undefined`
`value`	`any`	`undefined`
`onValueChange`	`((value: unknown, event: Event) => void)`	`undefined`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`inputRef`	`Ref<HTMLInputElement>`	`undefined`
`className`	`\| string \| ((state: Radio.Group.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: Radio.Group.State) => ReactElement)`	`undefined`

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

Root

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

Prop	Type	Default
`value^*`	`any`	`—`
`nativeButton`	`boolean`	`true`
`disabled`	`boolean`	`false`
`readOnly`	`boolean`	`false`
`required`	`boolean`	`false`
`inputRef`	`Ref<HTMLInputElement>`	`undefined`
`className`	`\| string \| ((state: Radio.Root.State) => string)`	`undefined`
`render`	`\| ReactElement \| ((props: HTMLProps, state: Radio.Root.State) => ReactElement)`	`undefined`

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.

Prop	Type	Default
`className`	`\| string \| ((state: Radio.Indicator.State) => string)`	`undefined`
`keepMounted`	`boolean`	`false`
`render`	`\| ReactElement \| ((props: HTMLProps, state: Radio.Indicator.State) => ReactElement)`	`undefined`

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).

Examples

Form integration

To use a radio group in a form:

Pass the group’s name to Field
Use Field.Label to label each radio
Use the render prop to render the field as a Fieldset in order to label the group

Using RadioGroup in a form

<Form>
  <Field.Root name="shipping" render={<Fieldset.Root />}>
    <Fieldset.Legend>Shipping method</Fieldset.Legend>
    <RadioGroup>
      <Field.Label>
        <Radio.Root value="standard" />
        Standard
      </Field.Label>
      <Field.Label>
        <Radio.Root value="express" />
        Express
      </Field.Label>
    <RadioGroup>
  </Field.Root>
</Form>