RadioGroup
Use a RadioGroup to control a group of radio buttons.
Quick Start
- Installation
npm install @adaptavant/eds-core- Import
import { RadioGroup } from '@adaptavant/eds-core';
Legend
Use legend prop to describe the purpose of the RadioGroup.
const [selected, setSelected] = React.useState('Daisy');
return (
<RadioGroup
description="Choose a character from the list below"
legend="Animation Characters"
name="animation-characters"
onChange={setSelected}
value={selected}
>
<Radio label="Olaf" value="Olaf" />
<Radio label="Minnie" value="Minnie" />
<Radio label="Daisy" value="Daisy" />
</RadioGroup>
);
Description
A description of the RadioGroup. Provides a hint such as specific requirements for what to choose.
const [selected, setSelected] = React.useState('Woody');
return (
<RadioGroup
description="Choose a character from the list below"
legend="Disney Characters"
name="disney-characters"
onChange={setSelected}
value={selected}
>
<Radio label="Ariel" value="Ariel" />
<Radio label="Woody" value="Woody" />
<Radio label="Simba" value="Simba" />
</RadioGroup>
);
Managing state
The RadioGroup component accepts a value and onChange prop, allowing you to control its state.
const [selected, setSelected] = React.useState('Shrek');
return (
<RadioGroup
description="Choose a character from the list below"
legend="Shrek Characters"
name="shrek-characters"
onChange={setSelected}
value={selected}
>
<Radio label="Shrek" value="Shrek" />
<Radio label="Fiona" value="Fiona" />
<Radio label="Donkey" value="Donkey" />
</RadioGroup>
);
Name
Use name prop to name the RadioGroup.
const [selected, setSelected] = React.useState('Pluto');
return (
<RadioGroup
description="Choose a character from the list below"
legend="Fictional Characters"
name="fictional-characters"
onChange={setSelected}
value={selected}
>
<Radio label="Pluto" value="Pluto" />
<Radio label="Rex" value="Rex" />
<Radio label="Rapunzel" value="Rapunzel" />
</RadioGroup>
);
Disabled
Use the isDisabled prop to indicate that a RadioGroup or Radio is inactive or inaccessible.
{/* disable the radio group */}
<RadioGroup
description="Please check all that apply."
isDisabled
legend="Preferred contact method"
>
<Radio label="Phone" value="Phone" />
<Radio label="Email" value="Email" />
<Radio label="SMS" value="Sms" />
</RadioGroup>
isDisabled prop accepts a boolean or a callback function.
const [selected, setSelected] = React.useState('Helga Hufflepuff');
const isDisabled = (value) => value === 'Salazar Slytherin';
return (
<RadioGroup
description="Choose a House from the list below"
legend="Hogwarts Houses"
name="hogwarts-houses"
onChange={setSelected}
value={selected}
isDisabled={isDisabled}
>
<Radio label="Godric Gryffindor" value="Godric Gryffindor" />
<Radio label="Salazar Slytherin" value="Salazar Slytherin" />
<Radio label="Helga Hufflepuff" value="Helga Hufflepuff" />
</RadioGroup>
);
API Reference
RadioGroup
| Prop | Type | Description | Default |
|---|---|---|---|
children | ReactNode | The Radio components to be included in the group. | |
description? | ReactNode | Helpful text that appears below the legend to provide additional information or instructions about the radio options. | |
errorMessage? | ReactNode | Text that appears when there's an error, such as when a required selection hasn't been made. Adds red styling to highlight the issue. | |
id? | string | A unique identifier for the radio group, useful for accessibility and form handling. | |
isRequired? | boolean | When true, indicates that the user must select one of the radio options before submitting the form. | false |
legend | ReactNode | The title or heading for the radio group that explains what the options are for. | |
orientation? | 'horizontal' | 'vertical' | Controls how the radio buttons are arranged - either side-by-side (horizontal) or stacked (vertical). | 'vertical' |
isDisabled? | boolean | Makes all radio buttons non-clickable when set to true. Can also be a function that decides which options should be disabled based on their value. | false |
name | string | A required field that groups the radio buttons together so only one can be selected at a time. Important for form submission. | |
onBlur? | (selectedValue: string) => void | A function that runs when the user clicks or tabs away from a radio button, receiving the currently selected value. | |
onChange | (selectedValue: string) => void | A required function that runs whenever the user selects a different radio option, receiving the newly selected value. | |
size? | 'standard' | 'large' | Controls the size of all radio buttons in the group - either normal sized or larger for better visibility. | 'standard' |
value | string | The currently selected radio button's value. Required to make this a controlled component. |
Note: The RadioGroup component inherits several props from the Fieldset component and combines them with radio-specific functionality to create accessible form controls.
Style API
Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.
Please refer to the Style API documentation for more insights.
RadioGroup parts
const [selected, setSelected] = React.useState('');
const error = selected.length === 0 ? 'Please select atleast one payment method' : '';
return (
<RadioGroup
legend="Payment Method"
name="payment"
onChange={setSelected}
value={selected}
description="Select your preferred payment method"
className="border border-input rounded-8px w-full p-4"
errorMessage={error}
classNames={{
legend: "text-positive underline",
description: "text-link italic",
errorMessage: "text-caution",
errorTrack: "bg-neutral-secondary px-2 py-1",
errorIcon: "fill-critical",
wrapper: "bg-neutral-secondary p-4 rounded-8px",
}}
>
<Radio label="Cash" value="cash" />
<Radio label="Credit Card" value="card" />
<Radio label="Bank Transfer" value="transfer" />
</RadioGroup>
);
| Stylable Parts | Description |
|---|---|
| root | The root container of the radio group component, wrapping all inner elements. |
| legend | The legend text that serves as the heading for the radio group. |
| description | Description text providing additional information about the radio group. |
| errorMessage | The error message text displayed when validation fails. |
| errorTrack | Container that wraps the error icon and error message. |
| errorIcon | The icon displayed alongside the error message. |
| wrapper | Container that wraps the radio options within the group. |
Usage guidelines
Do
- Single selection in lists, forms, or tables: Implement RadioGroup in lists, forms, or tables when users need to choose a single option from multiple related choices.
- Non-immediate selections: Use RadioGroup when the selection doesn't take immediate effect and requires form submission.
Don’t
- Multiple selections possible: Avoid using RadioGroup in situations where users can select multiple options; use Checkbox instead.
- Single item selection: If there's only one item to select or deselect, opt for Checkbox instead of RadioGroup.
- Immediate selections, especially on mobile: For selections that take immediate effect, particularly on mobile devices, use Toggle instead of RadioGroup.
- Visual clarity issues: If it's visually challenging to discern whether RadioGroup turns something on or off, prefer using Toggle for clearer visual feedback.
Best practices
Do
Utilise RadioGroup to choose a single option from a list containing two or more items.
Don’t
Use RadioGroup to select multiple items.
Do
Maintain clear and concise labels and legends to prevent an overwhelming amount of text that can be challenging to scan and may slow down the user. If additional clarification is required, consider employing IconButtons with Tooltips.
Don’t
Avoid using extensive text that gets truncated and fails to provide clear instructions on how to make a selection.
Do
Employ RadioGroup when seeking a definitive answer to a binary question that necessitates form submission.
Don’t
Opt for a RadioGroup to instantly toggle a state on and off on mobile; alternatively, use Toggle for this purpose.