Documentation
Radio
Radios allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare. Radio implementation is based on @react-aria/radio
import { Radio } from '@nextui-org/react';
Anatomy
- Radio.Group: Radio group component that holds all radios in a group and provides a common API for managing the group state.
- Radio: Radio component that represents a single option
Default
Radio.Group accepts multiple Radio elements as children. Each Radio represents an item that can only be checked singularly, labeled by its children.
Note: A Radio cannot be used outside of a Radio.Group.
Disabled
Unusable and un-clickable Radio.
Sizes
Change the size of the entire Radio including padding, font-size and border with the size property.
Colors
You can change the color with color prop.
Label Colors
You can change the Radio label color with labelColor prop.
Squared
You can change the full style to a squared Radio with the isSquared prop.
Description
You can add a description to the Radio with description prop.
Invalid
Radios can display a validation state to communicate to the user if the current value is invalid. Implement your own validation logic in your app and pass invalid to the Radio.Group via the validationState prop.
Row
Radio groups are vertically oriented by default. The orientation prop can be used to change the orientation to horizontal.
Disable Animation
You can disable the animation of the entire Radio with the property disableAnimation.
Controlled vs Uncontrolled
An initial, uncontrolled value can be provided to the Radio.Group using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.
Note: See React's documentation on uncontrolled components for more info.
Events
Radio.Group accepts an onChange prop, which is triggered when a user checks an item from the list. The example below uses onChange to log how the user is interacting with the component.
A11y: If a visible label isn't specified for a
Radio.Group, an aria-label must be provided for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.Radioelements within a group should always have a visible label.
Keyboard Interactions
| Key | Description |
|---|---|
| ArrowDown ArrowRight | When focus is on an item, moves focus to the next item. |
| ArrowUp ArrowLeft | When focus is on an item, moves focus to the previous item. |
APIs
Radio.Group Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| children* | ReactNode[] | The content of the radio group. It must be a list of radio items. | - |
| label | ReactNode | The content to display as the label. | - |
| value | string | The current value (controlled). | - |
| defaultValue | string | The default value (uncontrolled). | - |
| color | SimpleColors string | Change radio group color | primary |
| labelColor | SimpleColors string | Change radio group label color | default |
| size | NormalSizes | Size of all radios in the group | md |
| name | string | The name of the RadioGroup, used when submitting an HTML form. See MDN | - |
| orientation | horizontal vertical | The axis the radio group items should align with. | vertical |
| validationState | valid invalid | Whether the input should display its "valid" or "invalid" visual styling. | - |
| isDisabled | boolean | Whether the radio group items are disabled. | false |
| isReadOnly | boolean | Whether the input can be selected but not changed by the user. | false |
| isRequired | boolean | Whether user input is required on the input before form submission. Often paired with the necessityIndicator prop to add a visual indicator to the input. | false |
| css | Stitches.CSS | Override Default CSS style | - |
| as | keyof JSX.IntrinsicElements | Changes which tag component outputs | div |
Radio.Group Events
| Attribute | Type | Description | Default |
|---|---|---|---|
| onChange | (value: T) => void | Handler that is called when the value changes. | - |
Radio.Group Accessibility Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| id | string | The element's unique identifier. See MDN | - |
| aria-label | string | Defines a string value that labels the current element | - |
| aria-labelledby | string | Identifies the element (or elements) that labels the current element | - |
| aria-describedby | string | Identifies the element (or elements) that describes the object. | - |
| aria-details | string | Identifies the element (or elements) that provide a detailed, extended description for the object. | - |
| aria-errormessage | string | Identifies the element that provides an error message for the object. | - |
Radio Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| value* | string | The value of the radio button, used when submitting an HTML form. See MDN | - |
| children | ReactNode | The label for the Radio. Accepts any renderable node. | - |
| color | SimpleColors string | The radio color | primary |
| labelColor | SimpleColors string | The radio label color | default |
| description | string ReactNode | The radio description text | - |
| size | NormalSizes | The radio size | md |
| isSquared | boolean | Whether the radio button has squared corners | false |
| isDisabled | boolean | Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance. | false |
| disableAnimation | boolean | Whether the checkbox has animations | false |
| autoFocus | boolean | Whether the element should receive focus on render. | false |
| css | Stitches.CSS | Override Default CSS style | - |
| as | keyof JSX.IntrinsicElements | Changes which tag component outputs | label |
Radio Events
| Attribute | Type | Description | Default |
|---|---|---|---|
| onFocus | (e: FocusEvent) => any | Handler that is called when the element receives focus. | - |
| onBlur | (e: FocusEvent) => any | Handler that is called when the element loses focus. | - |
| onFocusChange | (isFocused: boolean) => void | Handler that is called when the element's focus status changes. | - |
| onKeyDown | (e: KeyboardEvent) => any | Handler that is called when a key is pressed. | - |
| onKeyUp | (e: KeyboardEvent) => any | Handler that is called when a key is released. | - |
Radio Accessibility Props
| Attribute | Type | Description | Default |
|---|---|---|---|
| id | string | The element's unique identifier. See MDN | - |
| aria-label | string | Defines a string value that labels the current element | - |
| aria-labelledby | string | Identifies the element (or elements) that labels the current element | - |
| aria-describedby | string | Identifies the element (or elements) that describes the object. | - |
| aria-details | string | Identifies the element (or elements) that provide a detailed, extended description for the object. | - |
Radio types
Simple Colors
type SimpleColors = | 'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'error';
Normal Sizes
type NormalSizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
