Radio
An easily stylable radio button component.
View as MarkdownAnatomy
Radio is always placed within Radio Group. Import the components and place them together:
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.
name
string
string
- Name
- Description
Identifies the field when a form is submitted.
- Type
string
defaultValue
unknown
unknown
- Name
- 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
unknown
value
unknown
unknown
- Name
- 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
unknown
onValueChange
function
function
- Name
- Description
Callback fired when the value changes.
- Type
((value: unknown, event: Event) => void)
disabled
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the component should ignore user interaction.
- Type
boolean
- Default
false
readOnly
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user should be unable to select a different radio button in the group.
- Type
boolean
- Default
false
required
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user must choose a value before submitting a form.
- Type
boolean
- Default
false
inputRef
Ref<HTMLInputElement>
Ref<HTMLInputElement>
- Name
- Description
A ref to access the hidden input element.
- Type
Ref<HTMLInputElement>
className
string | function
string | function
- Name
- Description
CSS class applied to the element, or a function that returns a class based on the component’s state.
- Type
| string
| ((state: Radio.Group.State) => string)
render
ReactElement | function
ReactElement | function
- Name
- 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.Group.State) => ReactElement)
data-disabled
Present when the radio group is disabled.
Root
Represents the radio button itself.
Renders a <button>
element and a hidden <input>
beside.
value*
any
any
- Name
- Description
The unique identifying value of the radio in a group.
- Type
any
nativeButton
boolean
(default: true
)
boolean
true
- Name
- Description
Whether the component renders a native
<button>
element when replacing it via therender
prop. Set tofalse
if the rendered element is not a button (e.g.<div>
).- Type
boolean
- Default
true
disabled
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the component should ignore user interaction.
- Type
boolean
- Default
false
readOnly
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user should be unable to select the radio button.
- Type
boolean
- Default
false
required
boolean
(default: false
)
boolean
false
- Name
- Description
Whether the user must choose a value before submitting a form.
- Type
boolean
- Default
false
inputRef
Ref<HTMLInputElement>
Ref<HTMLInputElement>
- Name
- Description
A ref to access the hidden input element.
- Type
Ref<HTMLInputElement>
className
string | function
string | function
- Name
- 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)
render
ReactElement | function
ReactElement | function
- Name
- 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).
Indicator
Indicates whether the radio button is selected.
Renders a <span>
element.
className
string | function
string | function
- Name
- 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)
keepMounted
boolean
(default: false
)
boolean
false
- Name
- Description
Whether to keep the HTML element in the DOM when the radio button is inactive.
- Type
boolean
- Default
false
render
ReactElement | function
ReactElement | function
- Name
- 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).
Examples
Form integration
To use a radio group in a form:
- Pass the group’s
name
toField
- Use
Field.Label
to label each radio - Use the
render
prop to render the field as aFieldset
in order to label the group
<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>