About Project Overview Contributing Getting Started Installation Usage Themes Customizing Frameworks React Vue Angular GitHub Light Dark System

Radio

<terra-radio> | TerraRadio
Since 1.0 stable

Radio buttons are a form field used when only a single selection can be made from a list.

Option 1
<terra-radio>Option 1</terra-radio>

Examples

Basic Radio Buttons

Radio buttons always include a label and are stacked vertically or horizontally to form a list of options. Any list of radio buttons should appear with a default selection already made.

Option 1 Option 2 Option 3 
<div style="display: flex; flex-direction: column; gap: 0.75rem;">
  <terra-radio checked>Option 1</terra-radio>
  <terra-radio>Option 2</terra-radio>
  <terra-radio>Option 3</terra-radio>
</div>

Horizontal Layout

Radio buttons can also be arranged horizontally.

Yes No 
<div style="display: flex; gap: 1.5rem;">
  <terra-radio checked>Yes</terra-radio>
  <terra-radio>No</terra-radio>
</div>

Sizes

Radio buttons come in three sizes: small, medium (default), and large.

Small Medium Large 
<div style="display: flex; flex-direction: column; gap: 0.75rem;">
  <terra-radio size="small" checked>Small</terra-radio>
  <terra-radio size="medium" checked>Medium</terra-radio>
  <terra-radio size="large" checked>Large</terra-radio>
</div>

Disabled State

Use the disabled attribute to disable a radio button.

Disabled unchecked Disabled checked 
<div style="display: flex; flex-direction: column; gap: 0.75rem;">
  <terra-radio disabled>Disabled unchecked</terra-radio>
  <terra-radio disabled checked>Disabled checked</terra-radio>
</div>

Radio Groups

Radio buttons are typically used within a radio group to ensure only one option can be selected at a time. Use the terra-radio-group component to group related radio buttons together. The radio group automatically syncs the name attribute to all child radio buttons.

Articles Features Press Releases 
<terra-radio-group name="content-type" value="articles" label="Content Type">
  <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>

When using radio buttons within a radio group, you don’t need to set the name attribute on individual radio buttons - the group will automatically sync it.

Form Integration

Radio buttons work seamlessly with native HTML forms.

Select Content Type
Articles Features Press Releases 
<form id="content-form">
  <fieldset>
    <legend>Select Content Type</legend>
    <div style="display: flex; flex-direction: column; gap: 0.75rem; margin-top: 0.5rem;">
      <terra-radio name="content-type" value="articles" checked>Articles</terra-radio>
      <terra-radio name="content-type" value="features">Features</terra-radio>
      <terra-radio name="content-type" value="press-releases">Press Releases</terra-radio>
    </div>
  </fieldset>
</form>

Best Practices

  • Always include labels: Radio buttons should always have a clear, descriptive label that explains what the option does.
  • Stack vertically or horizontally: Radio buttons can be arranged vertically (most common) or horizontally for simple yes/no choices.
  • Default selection: Any list of radio buttons should appear with a default selection already made.
  • Use for single selection: Radio buttons 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 to group related radio buttons, especially in forms.
  • Mutually exclusive: Radio buttons are for mutually exclusive choices. If choices are not mutually exclusive, use checkboxes.

Accessibility

  • Radio buttons are keyboard accessible and can be activated with the Space or Arrow keys
  • The component properly associates labels with the radio input
  • Focus states are clearly visible with a focus ring
  • Radio buttons are properly grouped using aria-checked and role="radio"
  • When used in a radio group, keyboard navigation between options is handled automatically

[component-metadata:terra-radio]

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.

Script Import Bundler React

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/radio.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/radio.js';

To import this component using a bundler:

import '@nasa-terra/components/dist/components/radio/radio.js';

To import this component as a React component:

import TerraRadio from '@nasa-terra/components/dist/react/radio';

Slots

Name Description
(default) The radio’s label.

Learn more about using slots.

Properties

Name Description Reflects Type Default
name The name of the radio, submitted as a name/value pair with form data. string ''
value The radio’s value. When selected, the radio group will receive this value. string -
size The radio’s size. When used inside a radio group, the size will be determined by the radio group’s size so this attribute can typically be omitted. 'small' | 'medium' | 'large' 'medium'
disabled Disables the radio. boolean false
checked Draws the radio in a checked state. boolean false
defaultChecked The default value of the form control. Primarily used for resetting the form control. boolean false
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 Makes the radio a required field. 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-blur onTerraBlur Emitted when the radio loses focus. -
terra-change onTerraChange Emitted when the checked state changes. -
terra-focus onTerraFocus Emitted when the radio gains focus. -
terra-input onTerraInput Emitted when the radio receives 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
click() Simulates a click on the radio. -
focus() Sets focus on the radio. options: FocusOptions
blur() Removes focus from the radio. -
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. The value provided will be shown to the user when the form is submitted. To clear the custom validation message, call this method with an empty string. message: string

Learn more about methods.

Custom Properties

Name Description Default
--terra-radio-* All radio design tokens from horizon.css are supported.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s base wrapper.
control The circular container that wraps the radio’s checked state.
control--checked The radio control when the radio is checked.
checked-icon The checked icon, an SVG element.
label The container that wraps the radio’s label.

Learn more about customizing CSS parts.