Pharos
JSTOR's Design System
 Getting started Help FAQs DocumentationDevelopment GitHub JSTOR LogosTypographyColorImageryIconographyElevationVoice and toneJSTOR termsWeb elementsGrammar and styleEditing checklistAlertButtonBreadcrumbCheckboxCheckbox groupCoach MarkComboboxDropdown menuDropdown menu navFooterHeaderHeadingIconImage cardInput groupLayoutLinkLoading spinnerModalMultiselect dropdownPaginationPillPopoverProgress barRadio buttonRadio groupSelectSheetSidenavSliderSwitchTableTabsToastTooltipText inputTextareaToggle button groupOverviewAlias colorsGlobal colorsFont familyFont sizeFont weightLine heightElevationRadiusSpacingTransitionsType scaleType styles
Skip to main navigation
Radio button
Radio buttons present items in a list of two or more options where the user can select only one option at a time.
Example
I am a radio

See live code examples in Storybook
Usage

Radio buttons are normally presented in radio groups (a collection of radio buttons which will be grouped by the radio button group component). Only one radio button in a group can be selected at a time.

Best practices
Dos
  • Use a label to provide context for radio buttons
  • Include two or more mutually exclusive items in a group
  • Use when users need to see the available options at a glance
  • Use horizontally oriented only if there are a few options
Don'ts
  • Don't use radio buttons when there are either no choices or multiple choices per group
  • Don't display a set of radio buttons without a default selection
  • Don't use radio buttons if the list of choices gets long. (The select component may be better suited)
Content guidelines Labels
  • Labels are descriptive and succinct. They should provide further clarity for the user.
  • Labels should not end in punctuation.
  • Avoid using negative language, as it can be counterintuitive. For example, "I want to receive a promotional email" instead of "I don't want to receive promotional email."
States Default

Indicates that the user can interact with the radio button.

Radio label
Checked

Indicates the value used for the radio group.

Radio label
Disabled

Indicates that the user can interact with the radio button.

Radio label
Error

Indicates that an error has occurred with the radio button.

Radio label
Accessibility Relevant WCAG guidelines
  • 1.3.1 Info and Relationships A
  • 3.3.2 Labels or Instructions A
Importance
  • Uses aria-checked attribute to make sure the information communicated to assistive technology is the same as the visual state. (e.g. img element)
  • Use disabled prop to prevent the checkbox from interaction
  • Do we allow for help text?
  • Let's look at theWCAG guidelines
Code expectations
  • Provide a fieldset that surrounds the entire grouping of radio buttons. Also, provide alegend, which is a description for the grouping.Here's an example.
  • Some assistive technology read the legend ("title" prop for radio group) for each fieldset. It should be brief and descriptive to help someone using assistive technology quickly understand the question they are answering with the group of radio buttons.
  • Each radio button element has a role of "radio".
  • If a radio button is checked, the radio element has "aria-checked" set to true. If it is not checked, it has "aria-checked" set to false.
Expected actions Screen reader
  • Reads the label, the option, checked or unchecked and X out of X.
    • For example:
      • Download file as:
        • .doc
        • .pdf
    • The above example (with focus on the .doc and is NOT checked) should read as "Download file as, .doc, unchecked, 1 of 2"
      • Example
Keyboard
  • Space checks the focused radio button, if it is not already checked.
  • ↑ / ← move the indicator/focus to the radio button before the current selected
  • ↓ / → move the indicator/focus to the radio button after the current selected
  • Tab / Shift + Tab moves the focus into and out of the radio group. When focus moves into a radio group:
    • If a radio button is checked, focus is set on the checked button.
    • If none of the radio buttons are checked, focus is set on the first radio button in the group.