- Components
- Inputs
- Radio Group
Radio Group
A radio group allows a user to select a single item from a list of mutually exclusive options.
Installation
Install the following dependencies:
Copy and paste the following code into your project.
Update the import paths to match your project setup.
Usage
Use radio group to allow users to select a single option from a short list of related options.
Options
Orientation
RadioGroups are vertically oriented by default. The orientation prop can be used to change the orientation to 'horizontal'.
Variant
Use the variant prop to control the visual style of the radio buttons.
label
A visual label can be provided for the radio group using the label prop or a hidden label using aria-label prop.
Description
A description can be supplied to a radio group via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.
Contextual help
A ContextualHelp element may be placed next to the label to provide additional information or help about a CheckboxGroup.
Error message
An errorMessage can be supplied to a RadioGroup, which will be displayed when the isInvalid prop is set to true.
Disabled
Use the isDisabled prop to disable the RadioGroup or a single Radio.
Read only
The isReadOnly prop makes the selection immutable. Unlike isDisabled, the RadioGroup remains focusable.
Required
Use the isRequired prop to mark the radio group as required. Use the necessityIndicator prop to control the visual style of the required state.
Uncontrolled
The defaultValue prop can be used to set the default state.
Controlled
Use the value and onChange props to control the value of the radio group.
Composition
If you need to customize things further, you can drop down to the composition level.
API Reference
RadioGroup
Prop | Type | Default | Description |
---|---|---|---|
variant | "default" | "card" | "default" | The visual style of the radio group. |
orientation | 'horizontal' | 'vertical' | 'vertical' | The axis the Radio Button(s) should align with. |
value | string | null | - | The current value (controlled). |
defaultValue | string | null | - | The default value (uncontrolled). |
isDisabled | boolean | - | Whether the input is disabled. |
isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
name | string | - | The name of the input element, used when submitting an HTML form. |
isRequired | boolean | - | Whether user input is required on the input before form submission. |
isInvalid | boolean | - | Whether the input value is invalid. |
validate | (value: string | null) => ValidationError| true| null| 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. |
validationBehavior | 'native' | 'aria' | '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. |
children | ReactNode | (values: RadioGroupRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
Event | Type | Description |
---|---|---|
onChange | (isSelected: boolean) => void | Handler that is called when the element's selection state changes. |
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent<Target>) => void | Handler that is called when the element loses focus. |
onFocusChange | (isFocused: boolean) => void | Handler that is called when the element's focus status changes. |
Data attribute | Description |
---|---|
[data-orientation="horizontal | vertical"] | The orientation of the radio group. |
[data-disabled] | Whether the radio group is disabled. |
[data-readonly] | Whether the radio group is read only. |
[data-invalid] | Whether the radio group invalid. |
[data-required] | Whether the radio group is required. |
Radio
Prop | Type | Default | Description |
---|---|---|---|
variant | "default" | "card" | "default" | The visual style of the radio. |
value* | string | - | The value of the radio button, used when submitting an HTML form. |
inputRef | MutableRefObject<HTMLInputElement> | - | A ref for the HTML input element. |
isDisabled | boolean | - | Whether the radio button is disabled or not. Shows that a selection exists, but is not available in that circumstance. |
autoFocus | boolean | - | Whether the element should receive focus on render. |
children | ReactNode | (values: RadioRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
Event | Type | Description |
---|---|---|
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent<Target>) => void | 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) => void | Handler that is called when a key is pressed. |
onKeyUp | (e: KeyboardEvent) => void | Handler that is called when a key is released. |
onHoverStart | (e: HoverEvent) => void | Handler that is called when a hover interaction starts. |
onHoverEnd | (e: HoverEvent) => void | Handler that is called when a hover interaction ends. |
onHoverChange | (isHovering: boolean) => void | Handler that is called when the hover state changes. |
Data attribute | Description |
---|---|
[data-selected] | Whether the radio is selected. |
[data-hovered] | Whether the radio is currently hovered with a mouse. |
[data-pressed] | Whether the radio is currently in a pressed state. |
[data-focused] | Whether the radio is focused, either via a mouse or keyboard. |
[data-focus-visible] | Whether the radio is keyboard focused. |
[data-disabled] | Whether the radio is disabled. |
[data-readonly] | Whether the radio is read only. |
[data-invalid] | Whether the radio invalid. |
[data-required] | Whether the radio is required. |
Accessibility
Keyboard interactions
Key | Description |
---|---|
Tab | Moves focus to either the checked radio item or the first radio item in the group. |
Space | When focus is on an unchecked radio item, checks it. |
ArrowDown | Moves focus and checks the next radio item in the group. |
ArrowUp | Moves focus to the previous radio item in the group. |
ArrowRight | Moves focus and checks the next radio item in the group. |
ArrowLeft | Moves focus to the previous radio item in the group. |