Radio

An easily stylable radio button component.

View as Markdown
Best apple

Anatomy

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

Anatomy

API reference

RadioGroup

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

name

string

Name
Description

Identifies the field when a form is submitted.

Type

string

defaultValue

unknown

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

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

Description

Callback fired when the value changes.

Type

((value: unknown, event: Event) => void)

disabled

boolean

(default:

false

)
Description

Whether the component should ignore user interaction.

Type

boolean

Default

false

readOnly

boolean

(default:

false

)
Description

Whether the user should be unable to select a different radio button in the group.

Type

boolean

Default

false

required

boolean

(default:

false

)
Description

Whether the user must choose a value before submitting a form.

Type

boolean

Default

false

inputRef

Ref<HTMLInputElement>

Description

A ref to access the hidden input element.

Type

Ref<HTMLInputElement>

className

string | function

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

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

Name
Description

The unique identifying value of the radio in a group.

Type

any

nativeButton

boolean

(default:

true

)
Description

Whether the component renders a native <button> element when replacing it via the render prop. Set to false if the rendered element is not a button (e.g. <div>).

Type

boolean

Default

true

disabled

boolean

(default:

false

)
Description

Whether the component should ignore user interaction.

Type

boolean

Default

false

readOnly

boolean

(default:

false

)
Description

Whether the user should be unable to select the radio button.

Type

boolean

Default

false

required

boolean

(default:

false

)
Description

Whether the user must choose a value before submitting a form.

Type

boolean

Default

false

inputRef

Ref<HTMLInputElement>

Description

A ref to access the hidden input element.

Type

Ref<HTMLInputElement>

className

string | function

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

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

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

)
Description

Whether to keep the HTML element in the DOM when the radio button is inactive.

Type

boolean

Default

false

render

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:

  1. Pass the group’s name to Field
  2. Use Field.Label to label each radio
  3. Use the render prop to render the field as a Fieldset in order to label the group
Using RadioGroup in a form