Radio
Radio Buttons allow a user to select one value from a predefined list of 7 or fewer options.
Component Type
Input
Platform
Web
Component
Sana Canvas
Delivery Channels
Web
Version
16.2.12Experience Surfaces
Page Body Inline
Radio (Preview) vs. Radio (Main)
@workday/canvas-kit-preview-react) documented here on this page. The Radio component in the Main package (@workday/canvas-kit-react) will eventually be replaced with the Radio component in the Preview package. See the Packages Glossary for what Preview means.Anatomy

- Form Field Label: The Form Field Label describes all of the Radio in the Radio group and functions as a header.
- Radio Button: Radio Buttons are vertically aligned and in close proximity to its own label.
- Radio Label: Radio Labels give information about what to select.
Usage Guidance
- The Form Field Label can be positioned in two places; above or left of Radio group for LTR languages. Form Field Labels are aligned to the right of Radio group for RTL languages.
- Radio Labels are positioned to the right of Radio Buttons for LTR languages or to the left of Radio Buttons for RTL languages.
- You can configure one Radio Button in the group preselected by default. This default option should be the safest option presenting the least risk to the user, or be the option most commonly selected.
- If the user is allowed to not select any of the options, provide a “None” option.
- If the list doesn’t encompass all possible values in 7 or less options, provide a Radio Button marked “Other.”
When to Use
- Use Radio Buttons when a user is only allowed to select 1 value from a list of 7 or less options.
When to Use Something Else
- Consider using a Switch if the only options are yes or no.
- If a user is allowed to select 0, 1, or multiple values from a predefined list of 7 or less options, consider using Checkboxes or a Select to select one option.
- Use a Prompt when the number of list items is large or unknown. Prompts have search capabilities and folders which provide users with the means to browse options. Prompts can be configured to support single or multi-select.
Examples
Basic Example
Our radio component includes a RadioGroup container and RadioGroup.RadioButton, which renders an
individual radio button. Nest related RadioGroup.RadioButton buttons within a RadioGroup and
provide a name prop to the RadioGroup to group the radio buttons together. Each
RadioGroup.RadioButton must have a unique value. This value is used in conjunction with the
value prop set on the RadioGroup to determine which radio button is selected. To tie it all
together, provide an onChange handler to the RadioGroup to track the selected value as it
changes.
RadioGroup should be used in tandem with
FormFieldGroup. FormFieldGroup.Label names the
group, and FormFieldGroup.Input associates hint, error, and required state with each radio.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
const formfieldInputStyles = createStyles({
width: px2rem(200),
});
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<Flex cs={{flexDirection: 'column'}}>
<FormFieldGroup>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
cs={formfieldInputStyles}
as={RadioGroup}
name="pizza-crust"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="custom">
Butter - the best thing to put on bread
</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup.Field>
</FormFieldGroup>
Value selected: {value}
</Flex>
);
};
Our example uses React state to track the
value of the RadioGroup.
Inverse
Set the variant prop of RadioGroup.RadioButton to inverse to ensure proper contrast on dark
backgrounds.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {Box} from '@workday/canvas-kit-react/layout';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
const styleOverrides = {
containerStyles: createStyles({
backgroundColor: system.color.surface.contrast.default,
padding: system.padding.md,
}),
formFieldStyles: createStyles({
legend: {
color: system.color.fg.inverse,
},
}),
};
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<Box cs={styleOverrides.containerStyles}>
<RadioGroup name="crust-inverse" onChange={handleChange} value={value}>
<RadioGroup.RadioButton variant="inverse" value="deep-dish">
Deep dish
</RadioGroup.RadioButton>
<RadioGroup.RadioButton variant="inverse" value="thin">
Thin
</RadioGroup.RadioButton>
<RadioGroup.RadioButton variant="inverse" value="gluten-free">
Gluten free
</RadioGroup.RadioButton>
<RadioGroup.RadioButton variant="inverse" value="cauliflower">
Cauliflower
</RadioGroup.RadioButton>
</RadioGroup>
</Box>
);
};
Radio Group with No Value
Omit the value prop from RadioGroup to render the group with no selected
RadioGroup.RadioButton.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>(0);
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup>
<FormFieldGroup.Label as="legend">Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.List
as={RadioGroup}
name="crust-no-value"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup>
);
};
Ref Forwarding
RadioGroup.RadioButton supports ref forwarding .
It will forward ref to its underlying <input type="radio"> element.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const glutenFreeRef = React.useRef(null);
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
const handleClick = () => {
glutenFreeRef.current.click();
};
return (
<>
<FormFieldGroup>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.List as={RadioGroup} name="crust-ref" onChange={handleChange} value={value}>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free" ref={glutenFreeRef}>
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup>
<PrimaryButton onClick={handleClick}>Select Gluten Free</PrimaryButton>
</>
);
};
Label Position
Set the orientation prop of the Form Field to designate the position of the label relative to the
input component. By default, the orientation will be set to vertical.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup orientation="horizontalStart">
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
as={RadioGroup}
name="crust-label"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup.Field>
</FormFieldGroup>
);
};
Required
Set the isRequired prop of the wrapping FormFieldGroup to true to indicate that the field is
required. Labels for required fields are suffixed by a red asterisk.
You must choose a crust
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup isRequired={true}>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.List
as={RadioGroup}
name="crust-required"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
<FormFieldGroup.Hint>You must choose a crust</FormFieldGroup.Hint>
</FormFieldGroup>
);
};
Disabled
Set the disabled prop of RadioGroup.RadioButton to prevent users from interacting with it. Be
careful not to disable a pre-selected radio button as this will block keyboard access to the entire
RadioGroup.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
as={RadioGroup}
name="crust-disabled"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} disabled value="gluten-free">
Gluten free (sold out)
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup.Field>
</FormFieldGroup>
);
};
Custom Radio Button
Use RadioGroup.Label instead of RadioGroup.RadioButton if you need direct access to the label
and the radio input. This will allow you to apply custom styling to the text and radio input.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {createStyles, px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
const styleOverrides = {
formfieldInputStyles: createStyles({
width: px2rem(200),
}),
radioGroupLabelTextStyles: createStyles({
color: system.color.fg.default,
}),
};
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<Flex cs={{flexDirection: 'column'}}>
<FormFieldGroup>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
as={RadioGroup}
name="pizza-crust-custom"
onChange={handleChange}
cs={styleOverrides.formfieldInputStyles}
value={value}
>
<RadioGroup.Label>
<FormFieldGroup.Input as={RadioGroup.Label.Input} value="deep-dish" />
<RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
Deep dish
</RadioGroup.Label.Text>
</RadioGroup.Label>
<RadioGroup.Label>
<FormFieldGroup.Input as={RadioGroup.Label.Input} value="gluten-free" />
<RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
Gluten free
</RadioGroup.Label.Text>
</RadioGroup.Label>
<RadioGroup.Label>
<FormFieldGroup.Input as={RadioGroup.Label.Input} value="cauliflower" />
<RadioGroup.Label.Text cs={styleOverrides.radioGroupLabelTextStyles}>
Cauliflower
</RadioGroup.Label.Text>
</RadioGroup.Label>
</FormFieldGroup.List>
</FormFieldGroup.Field>
</FormFieldGroup>
Value selected: {value}
</Flex>
);
};
Standalone Radio Button
Use StyledRadioButton when you want a styled radio button on its own without using RadioGroup.
You will need to handle behavior and accessibility.
import React from 'react';
import {StyledRadioButton} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
import {Flex} from '@workday/canvas-kit-react/layout';
import {px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<Flex cs={{flexDirection: 'column'}}>
<FormFieldGroup as="fieldset">
<FormFieldGroup.Label as="legend">Choose Your Pizza Crust</FormFieldGroup.Label>
<Flex cs={{gap: system.gap.xl}}>
<Flex as="label" cs={{gap: px2rem(12)}}>
<FormFieldGroup.Input
as={StyledRadioButton}
onChange={handleChange}
value="deep-dish"
name="pizza-crust-standalone"
checked={value === 'deep-dish'}
/>
Deep dish
</Flex>
<Flex as="label" cs={{gap: px2rem(12)}}>
<FormFieldGroup.Input
as={StyledRadioButton}
onChange={handleChange}
value="gluten-free"
checked={value === 'gluten-free'}
name="pizza-crust-standalone"
/>
Gluten free
</Flex>
</Flex>
</FormFieldGroup>
Value selected: {value}
</Flex>
);
};
Use RadioGroup.Label when you want more control styling the text and radio input but still want
some behavior handled for you.
Error States
Set the error prop of the wrapping FormFieldGroup to "caution" or "error" to set the group
to the alert or error state. Put the message in FormFieldGroup.Hint. FormFieldGroup.Input
associates that text with each radio.
Caution
Use the alert state when a selection is valid but there is additional information.
Deep dish is an extra $2.99.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup error="caution" id="hint-alert">
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
as={RadioGroup}
name="crust-alert"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
<FormFieldGroup.Hint>Deep dish is an extra $2.99.</FormFieldGroup.Hint>
</FormFieldGroup.Field>
</FormFieldGroup>
);
};
Error
Use the error state when the selection is no longer valid.
Deep dish is currently sold out.
import React from 'react';
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
export default () => {
const [value, setValue] = React.useState<string | number>('deep-dish');
const handleChange = (e: React.ChangeEvent) => {
const target = e.currentTarget;
if (target instanceof HTMLInputElement) {
setValue(target.value);
}
};
return (
<FormFieldGroup error="error">
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List
as={RadioGroup}
name="crust-error"
onChange={handleChange}
value={value}
>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="deep-dish">
Deep dish
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="thin">
Thin
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="gluten-free">
Gluten free
</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton} value="cauliflower">
Cauliflower
</FormFieldGroup.Input>
</FormFieldGroup.List>
<FormFieldGroup.Hint>Deep dish is currently sold out.</FormFieldGroup.Hint>
</FormFieldGroup.Field>
</FormFieldGroup>
);
};
React Hook Form
Using a form library like React Hook Form is a common use case.
Reference this CodeSandbox on
how to use RadioGroup with React Hook Form.
Custom Styles
Radio and its subcomponents support custom styling via the cs prop. For more information, check
our
“How To Customize Styles” .
Accessibility
The primary accessibility goal is to ensure users can identify the radio group and each option, determine which option is selected, and hear associated hints, errors, and required state when a radio receives focus. Use Radio when the user must choose one option from a list. For independent options, use Checkbox instead.
Minimum Accessible Structure
The following matches the Basic Example: a FormFieldGroup with
FormFieldGroup.List as={RadioGroup}, and two or more
FormFieldGroup.Input as={RadioGroup.RadioButton} options.
import {RadioGroup} from '@workday/canvas-kit-preview-react/radio';
import {FormFieldGroup} from '@workday/canvas-kit-react/form-field';
<FormFieldGroup>
<FormFieldGroup.Label>Choose Your Pizza Crust</FormFieldGroup.Label>
<FormFieldGroup.Field>
<FormFieldGroup.List as={RadioGroup}>
<FormFieldGroup.Input as={RadioGroup.RadioButton}>Deep dish</FormFieldGroup.Input>
<FormFieldGroup.Input as={RadioGroup.RadioButton}>Thin</FormFieldGroup.Input>
</FormFieldGroup.List>
</FormFieldGroup.Field>
</FormFieldGroup>;Each option needs visible text. See the Basic Example for selection behavior.
Built-in Behaviors
Canvas Kit applies these automatically when you compose FormFieldGroup with RadioGroup.
Do not duplicate them in consuming code.
ARIA and DOM (applied by RadioGroup and FormFieldGroup):
RadioGroup: Renders adiv. It does not setrole="radiogroup".RadioGroup.RadioButton: Renders a<label>around<input type="radio">and the visible text. The wrapping<label>is the association, so anhtmlForpairing is not needed. That text is the option’s accessible name, and clicking it selects the radio.
Keyboard (native radio behavior):
RadioGroup uses native radio keyboard behavior. Tab moves to the selected radio, or
to the first radio when none is selected, and then leaves the group. Arrow keys move and select
within the group.
Screen reader expectations (when built-in behaviors are used as intended):
- On focus, assistive technology announces the group name from
FormFieldGroup.Label, along with the option name, radio role, and checked state. - When applicable, it also announces required state, invalid state (
error="error"), and hint or error text. Caution does not setaria-invalid. - Disabled radios are announced as unavailable.
For group, hint, error, and required association, see FormField’s Built-in Behaviors.
Accessibility Requirements
Required in application code for an accessible Radio group. Rows marked (conditional) apply only when the situation matches—otherwise omit.
If no design spec is provided: use a visible FormFieldGroup.Label. On
FormFieldGroup.List as={RadioGroup}, set a shared name and render two or more
RadioGroup.RadioButton options with visible text and their own value. Omit error,
isRequired, FormFieldGroup.Hint, disabled, aria-describedby on
RadioGroup, error on RadioGroup, a ref, and StyledRadioButton unless
the spec requires them.
Programmatic focus (conditional — omit by default):
Attach a ref only when the product must move focus to a radio after an action. Do not attach a
ref or call focus() unless the design or developer asks for it. See
Ref Forwarding.
| Requirement | How to satisfy |
|---|---|
| Group and option names | Use FormFieldGroup with a visible FormFieldGroup.Label. Render FormFieldGroup.List as={RadioGroup} with a shared name, and give every FormFieldGroup.Input as={RadioGroup.RadioButton} visible text and its own value. The shared name groups the inputs, and each option value is what the selected state matches. See Basic Example. |
| Error state (conditional) | When the selection is invalid, set error="error" on FormFieldGroup and prefix FormFieldGroup.Hint with “Error:”. See Error States. |
| Hint, caution, or required (conditional) | On FormFieldGroup, use FormFieldGroup.Hint for hint text, error="caution" for caution, and isRequired for required state, only when the spec includes that state. See Required and FormField accessibility. |
| Disabled (conditional) | Set disabled on an unavailable RadioGroup.RadioButton. Never disable the selected radio. See Disabled. |
Summary for code generation:
- REQUIRED:
FormFieldGroup, visibleFormFieldGroup.Label,FormFieldGroup.List as={RadioGroup}with a sharedname, and two or moreRadioGroup.RadioButtonoptions, each with visible text and its ownvalue - CONDITIONAL: when the selection is invalid,
error="error"onFormFieldGroupandFormFieldGroup.Hintprefixed with “Error:”. Hint text,error="caution", andisRequiredonly when the spec includes that state. Alsodisabled(not on the selected radio). See FormField accessibility for group hint, caution, and required.
Anti-Patterns
Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):
- Add
role="radiogroup"toRadioGroup—FormFieldGroupprovides the group semantics - Manually set
aria-checked,aria-invalid,aria-required, oraria-describedby—RadioGroupandFormFieldGroup.Inputwire these attributes - Use
FormFieldwithuseFieldset, or sethintIdandhintText— group radios withFormFieldGroupand put the message inFormFieldGroup.Hint - Wrap radios in
FormField.Input— useFormFieldGroup.Input as={RadioGroup.RadioButton} - Use
StyledRadioButtonunless the spec requires a radio outsideRadioGroup. In that case supply accessible option and group names and the necessary behavior. See Standalone Radio Button - Intercept Tab or arrow keys — native radio behavior moves and selects within the group
- Set
disabledon the selected radio — that removes the group’s tab stop, so keyboard users cannot move within the group. See Disabled - Set
erroronRadioGroup— set it onFormFieldGroupso Canvas Kit provides both the visual and accessible error state. See Error States - Rely on color alone for an error or caution — include
FormFieldGroup.Hint. Useerror="error"when the selection is invalid soaria-invalidis set. See Error States
Component API
RadioGroup
Use RadioGroup to group a collection of RadioGroup.RadioButton components under a common name.
<RadioGroup name="pizza-crust" value="thin">
<RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
<RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
</RadioGroup>
Layout Component
RadioGroup supports all props from thelayout component.
Props
Props extend from div. Changing the as prop will change the element interface.
Props extend from . If a model is passed, props from RadioModelConfig are ignored.
| Name | Type | Description | Default |
|---|---|---|---|
error | | The type of error associated with the RadioGroup (if applicable). | |
theme | | ||
cs | | The | |
children | ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref<R = div> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model | | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
RadioGroup.RadioButton
RadioGroup.RadioButton renders an <input type="radio" /> and its associated <label> (using children as the label's contents).
This component should satisfy most use cases; use RadioGroup.Label and its sub components if you require more flexibility.
<RadioGroup name="pizza-crust" value="thin">
<RadioGroup.RadioButton value="deep-dish">Deep dish</RadioGroup.RadioButton>
<RadioGroup.RadioButton value="thin">Thin</RadioGroup.RadioButton>
</RadioGroup>
Layout Component
Radio supports all props from thelayout component.
Props
Props extend from input. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
children | ReactNode | The Radio input and label children of RadioLabel | |
theme | | ||
cs | | The | |
disabled | boolean | undefined | ||
variant | 'inverse' | undefined | ||
value | string | number | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref<R = input> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model | | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
RadioGroup.Label
Use RadioGroup.Label instead of RadioGroup.Radio if you need direct access to the label and the radio input.
This will render a <label> that wraps an <input type="radio" /> and a <span> for the label text.
<RadioGroup name"pizza-crust" value="deep-dish">
<RadioGroup.Label>
<RadioGroup.Label.Input value="deep-dish" />
<RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
</RadioGroup.Label>
</RadioGroup>
Layout Component
Radio.Label supports all props from thelayout component.
Props
Props extend from label. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
children | ReactNode | The Radio input and label children of RadioLabel | |
theme | | ||
cs | | The | |
disabled | boolean | undefined | ||
variant | 'inverse' | undefined | ||
value | string | number | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | label |
ref | React.Ref<R = label> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model | | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
RadioGroup.Label.Input
Use RadioGroup.Label.Input within a RadioGroup.Label to render the input portion of a radio button.
<RadioGroup name"pizza-crust" value="deep-dish">
<RadioGroup.Label>
<RadioGroup.Label.Input value="deep-dish" />
<RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
</RadioGroup.Label>
</RadioGroup>
Layout Component
RadioGroup.Label.Input supports all props from thelayout component.
Props
Props extend from input. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
children | ReactNode | The Radio input and label children of RadioLabel | |
theme | | ||
cs | | The | |
disabled | boolean | undefined | ||
variant | 'inverse' | undefined | ||
value | string | number | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref<R = input> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model | | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
RadioGroup.Label.Text
Use RadioGroup.Label.Text within a RadioGroup.Label to render the label text portion of a radio button.
<RadioGroup name"pizza-crust" value="deep-dish">
<RadioGroup.Label>
<RadioGroup.Label.Input value="deep-dish" />
<RadioGroup.Label.Text>Deep dish</RadioGroup.Label.Text>
</RadioGroup.Label>
</RadioGroup>
Props
Props extend from span. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
model | | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
Model
Content Guidelines
- Form Field Labels are written in title case.
- The Radio Label for each individual selection are kept as concise as possible and written in sentence case.