Radio group

Radio Group allow users to select a single option from a list of mutually exclusive options.

Storybook @nextui-org/radio React Aria Source Styles source

Installation

npx nextui-cli@latest add radio

No need to install this package if @nextui-org/react is already installed globally.

Import

Usage

Disabled

Default Value

With Description

Horizontal

Controlled

You can use the value and onValueChange properties to control the radio input value.

Note: NextUI Radio also supports native events like onChange, useful for form libraries such as Formik and React Hook Form.

Invalid

Slots

RadioGroup Slots
- base: Radio group root wrapper, it wraps the label and the wrapper.
- wrapper: Radio group wrapper, it wraps all Radios.
- label: Radio group label, it is placed before the wrapper.
- description: Description slot for the radio group.
- errorMessage: Error message slot for the radio group.
Radio Slots
- base: Radio root wrapper, it wraps all elements.
- wrapper: Radio wrapper, it wraps the control element.
- labelWrapper: Label and description wrapper.
- label: Label slot for the radio.
- control: Control element, it is the circle element.
- description: Description slot for the radio.

Custom Styles

You can customize the RadioGroup and Radio component by passing custom Tailwind CSS classes to the component slots.

Custom Implementation

In case you need to customize the radio group even further, you can use the useRadio hook to create your own implementation.

Data Attributes

RadioGroup has the following attributes on the base element:
- data-orientation: The orientation of the radio group. Based on orientation prop.
Radio has the following attributes on the base element:
- data-selected: When the radio is checked. Based on isSelected prop.
- data-pressed: When the radio is pressed. Based on usePress.
- data-invalid: When the radio is invalid. Based on validationState prop.
- data-readonly: When the radio is readonly. Based on isReadOnly prop.
- data-hover-unselected: When the radio is being hovered and unchecked. Based on useHover.
- data-hover: When the radio is being hovered. Based on useHover.
- data-focus: When the radio is being focused. Based on useFocusRing.
- data-focus-visible: When the radio is being focused with the keyboard. Based on useFocusRing.
- data-disabled: When the radio is disabled. Based on isDisabled prop.

Accessibility

Radio groups are exposed to assistive technology via ARIA.
Each radio is built with a native HTML <input> element, which can be optionally visually hidden to allow custom styling.
Full support for browser features like form autofill.
Keyboard event support for arrows keys.
Keyboard focus management and cross browser normalization.
Group and radio labeling support for assistive technology.

API

RadioGroup Props

Attribute	Type	Description	Default
children	`ReactNode` \| `ReactNode[]`	The list of radio elements.	-
label	`ReactNode`	The label of the radio group.	-
size	`sm` \| `md` \| `lg`	The size of the radios.	`md`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The color of the radios.	`primary`
orientation	`horizontal` \| `vertical`	The orientation of the radio group.	`vertical`
name	`string`	The name of the RadioGroup, used when submitting an HTML form. See MDN.	-
value	`string[]`	The current selected value. (controlled).	-
defaultValue	`string[]`	The default selected value. (uncontrolled).	-
description	`ReactNode`	Radio group description .	-
errorMessage	`ReactNode` \| `((v: ValidationResult) => ReactNode)`	Radio group error message.	-
validate	`(value: string) => ValidationError ｜ true ｜ null ｜ undefined`	Validate input values when committing (e.g. on blur), returning error messages for invalid values. Validation errors are displayed upon form submission if `validationBehavior` is set to `native`. For real-time validation, use the `isInvalid` prop.	-
validationBehavior	`native` \| `aria`	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.	`aria`
isDisabled	`boolean`	Whether the radio group is disabled.	`false`
isRequired	`boolean`	Whether user checkboxes are required on the input before form submission.	`false`
isReadOnly	`boolean`	Whether the checkboxes can be selected but not changed by the user.	-
isInvalid	`boolean`	Whether the radio group is invalid.	`false`
validationState	`valid` \| `invalid`	Whether the inputs should display its "valid" or "invalid" visual styling. (Deprecated) use isInvalid instead.	`false`
disableAnimation	`boolean`	Whether the animation should be disabled.	`false`
classNames	`Record<"base"｜ "wrapper"｜ "label", string>`	Allows to set custom class names for the radio group slots.	-

RadioGroup Events

Attribute	Type	Description
onChange	`React.ChangeEvent<HTMLInputElement>`	Handler that is called when the element's value changes. You can pull out the new value by accessing `event.target.value` (string).
onValueChange	`((value: string) => void)`	Handler that is called when the value changes.

Radio Props

Attribute	Type	Description	Default
children	`ReactNode`	The label of the radio.	-
label	`ReactNode`	The label of the radio.	-
size	`sm` \| `md` \| `lg`	The size of the radio.	`md`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The color of the radio.	`primary`
description	`ReactNode`	A description for the field. Provides a hint such as specific requirements for what to choose.	-
isDisabled	`boolean`	Whether the radio is disabled.	`false`
isRequired	`boolean`	Whether user checkboxes are required on the input before form submission.	`false`
isReadOnly	`boolean`	Whether the checkboxes can be selected but not changed by the user.	-
isInvalid	`boolean`	Whether the radio is invalid. This is based on the radio group `validationState` prop.	`false`
disableAnimation	`boolean`	Whether the animation should be disabled.	`false`
classNames	`Record<"base"｜ "wrapper"｜ "labelWrapper" ｜ "label" ｜ "control" ｜ "description", string>`	Allows to set custom class names for the radio slots.	-