Radio button
Material 3 radio-button guidance with accessible single-selection groups and browser form semantics.
Radio buttons let users select exactly one value from a mutually exclusive set. Group related options with RadioGroup so selection, labeling, validation, and keyboard behavior share one semantic boundary.
import { RadioButton, RadioGroup } from '@m3-ui/ui';
<RadioGroup name="density" defaultValue="standard" label="Density">
<RadioButton value="compact">Compact</RadioButton>
<RadioButton value="standard">Standard</RadioButton>
<RadioButton value="comfortable">Comfortable</RadioButton>
</RadioGroup>When to use
Use radio buttons when the user must choose one option from a visible set. Use checkboxes for independent choices and segmented single-choice controls when the compact connected Material presentation is more appropriate.
Group contract
RadioGroup owns the selected value and shared label, plus optional description and error text. It inherits React Aria value, validation, form, and event props rather than introducing a separate selection model.
The default vertical arrangement works for most sets. orientation="horizontal" is a layout choice for suitable short option sets; it does not define a new Material radio family.
Behavior and states
React Aria owns radio-group/radio semantics, arrow-key focus/selection behavior, disabled state, controlled/uncontrolled values, and form participation. Material tokens own the control geometry, selected dot, colors, ripple/state indication, and interaction target.
Keep every option in its logical RadioGroup so the browser exposes the one-of-many relationship correctly.
Accessibility
The group needs a meaningful shared label or accessible name, while each RadioButton needs an option label. Description/error text should describe the group or option state rather than relying on color alone.
Keyboard behavior follows the radio-group model; do not attach custom arrow-key handling that competes with React Aria selection/focus management.
API reference
RadioGroup
RadioGroup({ children, label, description, errorMessage, orientation, className, ...props }: RadioGroupProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
children* | ReactNode | — | — | @m3-ui/ui |
description | ReactNode | — | — | @m3-ui/ui |
errorMessage | ChildrenOrFunction<FieldErrorRenderProps> | — | — | @m3-ui/ui |
label | ReactNode | — | — | @m3-ui/ui |
Inherited React / web props (94)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-errormessage | string | undefined | — | Identifies the element that provides an error message for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
className | ClassNameOrFunction<RadioGroupRenderProps> | undefined | 'react-aria-RadioGroup' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
defaultValue | string | null | undefined | — | The default value (uncontrolled). | @react-types/shared |
dir | string | undefined | — | — | @react-types/shared |
form | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the input is disabled. | @react-types/shared |
isInvalid | boolean | undefined | — | Whether the input value is invalid. | @react-types/shared |
isReadOnly | boolean | undefined | — | Whether the input can be selected but not changed by the user. | @react-types/shared |
isRequired | boolean | undefined | — | Whether user input is required on the input before form submission. | @react-types/shared |
lang | string | undefined | — | — | @react-types/shared |
name | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). | @react-types/shared |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onBlur | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. | @react-types/shared |
onChange | ((value: string) => void) | undefined | — | Handler that is called when the value changes. | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onFocus | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. | @react-types/shared |
onFocusChange | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
orientation | Orientation | undefined | 'vertical' | The axis the Radio Button(s) should align with. | react-stately |
render | DOMRenderFunction<"div", RadioGroupRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
style | StyleOrFunction<RadioGroupRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
validate | ((value: string) => ValidationError | true | null | undefined) | undefined | — | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. | @react-types/shared |
validationBehavior | "native" | "aria" | undefined | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. | react-aria-components |
value | string | null | undefined | — | The current value (controlled). | @react-types/shared |
Source: packages/ui/src/components/RadioButton/RadioButton.tsx:86
Material fidelity and web adaptation
- Family
- Radio buttons
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- RadioButton · RadioGroup
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements Material radio-button selection visuals plus a group primitive with label, description, validation error, and vertical or horizontal arrangement.
- Behavior fidelity
- adapted: React Aria owns radio-group selection, keyboard navigation, labeling, descriptions, validation, and focus semantics. Material tokens and ripple presentation are layered onto that browser interaction model.
- Semantics fidelity
- adapted: React Aria owns radio-group selection, keyboard navigation, labeling, descriptions, validation, and focus semantics. Material tokens and ripple presentation are layered onto that browser interaction model.
- Adaptations
- React Aria owns radio-group selection, keyboard navigation, labeling, descriptions, validation, and focus semantics. Material tokens and ripple presentation are layered onto that browser interaction model.
Material provides the visual radio-selection pattern. React Aria/browser semantics provide group relationships, keyboard navigation, validation wiring, and native form behavior.
Related components
- Checkbox — independent selections.
- Segmented buttons — connected single-choice or multi-choice controls.
- Forms and validation — native form composition.