Radio

An easily stylable radio button component.

react-radio.tsx stencil-radio.tsx index.module.css stencil.css

'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>
  );
}

The Stencil example uses fs-radio-group, fs-radio-root, and fs-radio-indicator directly. The group owns selection and arrow-key navigation; its cancelable valueChange event provides event.detail.value for controlled consumers to write back. inputRef exposes the native radio input. The indicator unmounts when unchecked unless keepMounted is enabled. Use nativeButton (or the HTML native-button attribute) to render a native button instead of the default span.

Native labels, forms, the migrated Fieldset legend, and Field integration are supported. Field supplies validation, automatic field labels, and field-state attributes. The migrated Form adds inherited validation mode, consolidated values, form-level errors, and submit validation. React render, function-valued className/style, and React context are not Web Component APIs. No component-specific controller or hidden behavior is supplied by the docs.

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.

namestring—

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

defaultValueValue—

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: Value | undefined

valueValue—

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: Value | undefined

onValueChangefunction—

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

formstring—

Name: form
Description: Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.
Type: string | 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

inputRefReact.Ref<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) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: RadioGroup.State, ) => React.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) | undefined

data-disabled

Present when the radio group is disabled.

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

RadioGroup.PropsHide

Re-Export of RadioGroup props as RadioGroupProps

RadioGroup.StateHide

type RadioGroupState = {
  /** Whether the user should be unable to select a different radio button in the group. */
  readOnly: boolean;
  /** Whether the user must tick a radio button within the group before submitting a form. */
  required: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
}

RadioGroup.ChangeEventReasonHide

type RadioGroupChangeEventReason = 'none'

RadioGroup.ChangeEventDetailsHide

type RadioGroupChangeEventDetails = {
  /** The reason for the event. */
  reason: 'none';
  /** The native event associated with the custom event. */
  event: Event;
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
}

Root

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

value^*Value—

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

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

inputRefReact.Ref<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) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Radio.Root.State, ) => React.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) | undefined

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 a valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in an 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 a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in an 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).

Radio.Root.PropsHide

Re-Export of Root props as RadioRootProps

Radio.Root.StateHide

type RadioRootState = {
  /** Whether the radio button is currently selected. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to select the radio button. */
  readOnly: boolean;
  /** Whether the user must choose a value before submitting a form. */
  required: boolean;
  /** Whether the radio button has been touched (when wrapped in Field.Root). */
  touched: boolean;
  /** Whether the radio button's value has changed from its initial value (when wrapped in Field.Root). */
  dirty: boolean;
  /** Whether the radio button is in a valid state (when wrapped in Field.Root). */
  valid: boolean | null;
  /** Whether the radio button has a value (when wrapped in Field.Root). */
  filled: boolean;
  /** Whether the radio button is focused (when wrapped in Field.Root). */
  focused: boolean;
}

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

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Radio.Indicator.State, ) => React.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) | undefined

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 a valid state (when wrapped in Field.Root).

data-invalid

Present when the radio is in an 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).

data-starting-style

Present when the radio indicator begins animating in.

data-ending-style

Present when the radio indicator is animating out.

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 a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the radio is in an 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).
`data-starting-style`	Present when the radio indicator begins animating in.
`data-ending-style`	Present when the radio indicator is animating out.

Radio.Indicator.PropsHide

Re-Export of Indicator props as RadioIndicatorProps

Radio.Indicator.StateHide

type RadioIndicatorState = {
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
  /** Whether the radio button is currently selected. */
  checked: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the user should be unable to select the radio button. */
  readOnly: boolean;
  /** Whether the user must choose a value before submitting a form. */
  required: boolean;
  /** Whether the radio button has been touched (when wrapped in Field.Root). */
  touched: boolean;
  /** Whether the radio button's value has changed from its initial value (when wrapped in Field.Root). */
  dirty: boolean;
  /** Whether the radio button is in a valid state (when wrapped in Field.Root). */
  valid: boolean | null;
  /** Whether the radio button has a value (when wrapped in Field.Root). */
  filled: boolean;
  /** Whether the radio button is focused (when wrapped in Field.Root). */
  focused: boolean;
}