Radio Group
<terra-radio-group> | TerraRadioGroup
Radio groups are used to group multiple radio buttons so they function as a single form control.
<terra-radio-group name="example" value="option-1"> <terra-radio value="option-1">Option 1</terra-radio> <terra-radio value="option-2">Option 2</terra-radio> <terra-radio value="option-3">Option 3</terra-radio> </terra-radio-group>
Examples
Basic Radio Group
Radio groups are used to group multiple radio buttons so they function as a single form control. All radio
buttons in a group share the same name attribute.
<terra-radio-group name="content-type" value="articles"> <terra-radio value="articles">Articles</terra-radio> <terra-radio value="features">Features</terra-radio> <terra-radio value="press-releases">Press Releases</terra-radio> </terra-radio-group>
With Label
Use the label attribute or slot to provide a label for the radio group. Labels are required
for proper accessibility.
<terra-radio-group name="priority" value="medium" label="Priority Level"> <terra-radio value="low">Low</terra-radio> <terra-radio value="medium">Medium</terra-radio> <terra-radio value="high">High</terra-radio> </terra-radio-group>
Sizes
The radio group’s size will be applied to all child radio buttons.
<terra-radio-group name="size-small" value="option-1" size="small"> <terra-radio value="option-1">Small</terra-radio> <terra-radio value="option-2">Small</terra-radio> </terra-radio-group> <terra-radio-group name="size-medium" value="option-1" size="medium" style="margin-top: 1rem;"> <terra-radio value="option-1">Medium</terra-radio> <terra-radio value="option-2">Medium</terra-radio> </terra-radio-group> <terra-radio-group name="size-large" value="option-1" size="large" style="margin-top: 1rem;"> <terra-radio value="option-1">Large</terra-radio> <terra-radio value="option-2">Large</terra-radio> </terra-radio-group>
Required Field
Use the required attribute to ensure a selection is made before form submission.
<terra-radio-group name="required-example" required label="Select an Option"> <terra-radio value="option-1">Option 1</terra-radio> <terra-radio value="option-2">Option 2</terra-radio> <terra-radio value="option-3">Option 3</terra-radio> </terra-radio-group>
Help Text
Use the help-text attribute or slot to provide additional guidance.
<terra-radio-group name="help-text-example" value="option-1" label="Content Type" help-text="Select the type of content you want to filter"> <terra-radio value="option-1">Articles</terra-radio> <terra-radio value="option-2">Features</terra-radio> <terra-radio value="option-3">Press Releases</terra-radio> </terra-radio-group>
Form Integration
Radio groups work seamlessly with native HTML forms.
<form id="content-form"> <terra-radio-group name="content-type" value="articles" label="Content Type" required> <terra-radio value="articles">Articles</terra-radio> <terra-radio value="features">Features</terra-radio> <terra-radio value="press-releases">Press Releases</terra-radio> </terra-radio-group> </form>
Best Practices
- Always include labels: Radio groups should always have a clear, descriptive label that explains what the selection is for.
-
Default selection: Any list of radio buttons should appear with a default selection
already made (set the
valueattribute). - Use for single selection: Radio groups allow users to select only one option from a list. For multiple selections, use Checkboxes instead.
- Limit options: When there are 7 or more options to choose from, use a Select Field instead of radio buttons.
- Group related options: Use a fieldset and legend (or radio-group with label) to group related radio buttons, especially in forms.
- Provide help text when needed: Use help text to clarify what selecting an option will do, especially for filtering or settings.
Accessibility
- Radio groups are keyboard accessible and support arrow key navigation between options
- The component properly associates labels with the radio group using
aria-labelledby - Focus states are clearly visible with a focus ring
- Required fields are indicated with an asterisk
- Help text is properly associated with the radio group using
aria-describedby - Radio groups use
role="radiogroup"for proper ARIA semantics
[component-metadata:terra-radio-group]
Importing
If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.
To import this component from the CDN using a script tag:
<script type="module" src="https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/radio-group/radio-group.js"></script>
To import this component from the CDN using a JavaScript import:
import 'https://cdn.jsdelivr.net/npm/@nasa-terra/components@0.0.138/cdn/components/radio-group/radio-group.js';
To import this component using a bundler:
import '@nasa-terra/components/dist/components/radio-group/radio-group.js';
To import this component as a React component:
import TerraRadioGroup from '@nasa-terra/components/dist/react/radio-group';
Slots
| Name | Description |
|---|---|
| (default) | The default slot where <terra-radio> elements are placed. |
label
|
The radio group’s label. Required for proper accessibility. Alternatively, you can use the
label attribute.
|
help-text
|
Text that describes how to use the radio group. Alternatively, you can use the
help-text attribute.
|
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
label
|
The radio group’s label. Required for proper accessibility. If you need to display HTML, use the
label slot instead.
|
string
|
''
|
|
helpText
help-text
|
The radio groups’s help text. If you need to display HTML, use the help-text slot
instead.
|
string
|
''
|
|
name
|
The name of the radio group, submitted as a name/value pair with form data. |
string
|
'option'
|
|
value
|
The current value of the radio group, submitted as a name/value pair with form data. |
|
string
|
''
|
size
|
The radio group’s size. This size will be applied to all child radios and radio buttons. |
|
'small' | 'medium' | 'large'
|
'medium'
|
form
|
By default, form controls are associated with the nearest containing
<form> element. This attribute allows you to place the form control outside of
a form and associate it with the form that has this id. The form must be in the same
document or shadow root for this to work.
|
|
string
|
''
|
required
|
Ensures a child radio is checked before allowing the containing form to submit. |
|
boolean
|
false
|
validity
|
Gets the validity state object | - | - | |
validationMessage
|
Gets the validation message | - | - | |
updateComplete
|
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
terra-change
|
onTerraChange
|
Emitted when the radio group’s selected value changes. | - |
terra-input
|
onTerraInput
|
Emitted when the radio group receives user input. | - |
terra-invalid
|
onTerraInvalid
|
Emitted when the form control has been checked for validity and its constraints aren’t satisfied. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
checkValidity()
|
Checks for validity but does not show a validation message. Returns true when valid
and false when invalid.
|
- |
getForm()
|
Gets the associated form, if one exists. | - |
reportValidity()
|
Checks for validity and shows the browser’s validation message if the control is invalid. | - |
setCustomValidity()
|
Sets a custom validation message. Pass an empty string to restore validity. |
message:
|
focus()
|
Sets focus on the radio-group. |
options: FocusOptions
|
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--terra-radio-group-*
|
All radio group design tokens from horizon.css are supported. |
Learn more about customizing CSS custom properties.
Parts
| Name | Description |
|---|---|
form-control
|
The form control that wraps the label, input, and help text. |
form-control-label
|
The label’s wrapper. |
form-control-input
|
The input’s wrapper. |
form-control-help-text
|
The help text’s wrapper. |
Learn more about customizing CSS parts.