Radio button

Radio buttons are used to select a single item in a list of options.

Examples

Base

Select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__base_opt_1" label="Option 1" name="radios"></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__base_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__base_opt_1">
      <label class="chi-radio__label" for="example__base_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__base_opt_2">
      <label class="chi-radio__label" for="example__base_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

Checked

Use the checked boolean attribute to set the default value of a radio button input to true.

Select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__checked_opt_1" label="Option 1" name="radios" checked></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__checked_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__checked_opt_1" checked>
      <label class="chi-radio__label" for="example__checked_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__checked_opt_2">
      <label class="chi-radio__label" for="example__checked_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

Disabled

Use the disabled boolean attribute to prevent users from interacting with an input. Disabled inputs are not submitted with the form and can not receive any browsing events such as mouse clicks or focus.

Select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__disabled_opt_1" label="Option 1" name="radios" disabled></chi-radio-button>
  </div>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__disabled_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__disabled_opt_3" label="Option 3" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__disabled_opt_1" disabled>
      <label class="chi-radio__label" for="example__disabled_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__disabled_opt_2">
      <label class="chi-radio__label" for="example__disabled_opt_2">Option 2</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__disabled_opt_3">
      <label class="chi-radio__label" for="example__disabled_opt_3">Option 3</label>
    </div>
  </div>
</fieldset>

Required

Use the required boolean attribute to indicate which radio buttons must be completed before submitting a form.

Select an option*

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__required" aria-label="Required field">*</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__required_opt_1" label="Option 1" name="radios" required></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__required_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__required" aria-label="Required field">*</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__required_opt_1" required>
      <label class="chi-radio__label" for="example__required_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__required_opt_2">
      <label class="chi-radio__label" for="example__required_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

Optional

Use optional to help emphasize a group of radio button options are not required and can be skipped.

Select an option(optional)

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__optional" aria-label="Optional field">(optional)</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__optional_opt_1" label="Option 1" name="radios"></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__optional_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__optional" aria-label="Optional field">(optional)</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__optional_opt_1">
      <label class="chi-radio__label" for="example__optional_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__optional_opt_2">
      <label class="chi-radio__label" for="example__optional_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

Help

Use chi-label__help to include a help icon that displays helpful information about an input in a popover. A help icon must be contained within an icon button to ensure it receives focus when a user tabs through a form.

Select an option

Web Component
HTML Blueprint

<fieldset>
  <div class="chi-label__wrapper">
    <legend class="chi-label">Select an option</legend>
    <div class="chi-label__help">
      <chi-button id="example__help-button" type="icon" variant="flat" size="xs" aria-label="Help">
        <chi-icon icon="circle-info-outline" size="xs" aria-hidden="true"></chi-icon>
      </chi-button>
      <chi-popover id="example__help-popover" variant="text" arrow reference="#example__help-button" position="top">
        Helpful information goes here
      </chi-popover>
    </div>
  </div>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__help_opt_1" label="Option 1" name="radios"></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__help_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<script>
  var helpButton = document.getElementById("example__help-button");

  helpButton.addEventListener("click", () => {
    var popover = document.getElementById("example__help-popover");

    popover.toggle();
  });
</script>

This HTML Blueprint requires JavaScript. You may use your own solution, or use Chi's vanilla JavaScript solution, Chi.js.

<fieldset>
  <div class="chi-label__wrapper">
    <legend class="chi-label">Select an option</legend>
    <div class="chi-label__help">
      <button class="chi-button -icon -xs -flat" id="example__help-button" aria-label="Help" data-target="#example___help-popover">
        <i class="chi-icon icon-circle-info-outline" aria-hidden="true"></i>
      </button>
      <section class="chi-popover chi-popover--top -animated" id="example___help-popover" aria-modal="true" role="dialog" aria-hidden="true" x-placement="top">
        <div class="chi-popover__content">
          <p class="chi-popover__text">Helpful information goes here.</p>
        </div>
      </section>
    </div>
  </div>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__help_opt_1">
      <label class="chi-radio__label" for="example__help_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__help_opt_2">
      <label class="chi-radio__label" for="example__help_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

<script>chi.popover(document.getElementById('example__help-button'));</script>

Error

Use the -danger state to provide feedback to users when a selection has not been made. Once a selection has been made, the state must be removed. To meet accessibility requirements, danger inputs must include an error message explaining the failure and/or how to correct it.

Select an option*

Please select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__required" aria-label="Required field">*</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <chi-radio-button id="example__error_opt_1" label="Option 1" name="radios" state="danger" required></chi-radio-button>
  </div>
  <div class="chi-form__item">
    <chi-radio-button id="example__error_opt_2" label="Option 2" name="radios" state="danger"></chi-radio-button>
  </div>
  <div class="chi-label -status -danger">
    <chi-icon icon="circle-warning" aria-hidden="true"></chi-icon>
    Please select an option
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">
    Select an option
    <abbr class="chi-label__required" aria-label="Required field">*</abbr>
  </legend>
  <div class="chi-form__item -mb--1">
    <div class="chi-radio">
      <input class="chi-radio__input -danger" type="radio" name="radios" id="example__error_opt_1" required>
      <label class="chi-radio__label" for="example__error_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item">
    <div class="chi-radio">
      <input class="chi-radio__input -danger" type="radio" name="radios" id="example__error_opt_2">
      <label class="chi-radio__label" for="example__error_opt_2">Option 2</label>
    </div>
  </div>
  <div class="chi-label -status -danger">
    <i class="chi-icon icon-circle-warning" aria-hidden="true"></i>
    Please select an option
  </div>
</fieldset>

Layout Variations

Inline

Apply -inline to display two or more radio buttons in one row.

Select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -inline">
    <chi-radio-button id="example__inline_opt_1" label="Option 1" name="radios"></chi-radio-button>
  </div>
  <div class="chi-form__item -inline">
    <chi-radio-button id="example__inline_opt_2" label="Option 2" name="radios"></chi-radio-button>
  </div>
</fieldset>

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <div class="chi-form__item -inline">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__inline_opt_1">
      <label class="chi-radio__label" for="example__inline_opt_1">Option 1</label>
    </div>
  </div>
  <div class="chi-form__item -inline">
    <div class="chi-radio">
      <input class="chi-radio__input" type="radio" name="radios" id="example__inline_opt_2" disabled>
      <label class="chi-radio__label" for="example__inline_opt_2">Option 2</label>
    </div>
  </div>
</fieldset>

Radio Button List

Radio button lists are used to wrap a series of radio buttons in a list. To render a series of radio buttons in a list, apply the class -list to chi-form__item.

Select an option

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <ul class="chi-form__item -list">
    <li class="chi-form__item">
      <chi-radio-button id="example__list_opt_1" label="Option 1" name="radio-button-list"></chi-radio-button>
    </li>
    <li class="chi-form__item">
      <chi-radio-button id="example__list_opt_2" label="Option 2" name="radio-button-list"></chi-radio-button>
    </li>
    <li class="chi-form__item">
      <chi-radio-button id="example__list_opt_3" label="Option 3" name="radio-button-list"></chi-radio-button>
    </li>
    <li class="chi-form__item">
      <chi-radio-button id="example__list_opt_4" label="Option 4" name="radio-button-list"></chi-radio-button>
    </li>
    <li class="chi-form__item">
      <chi-radio-button id="example__list_opt_5" label="Option 5" name="radio-button-list"></chi-radio-button>
    </li>
  </ul>
</fieldset>

<fieldset>
  <legend class="chi-label">Select an option</legend>
  <ul class="chi-form__item -list">
    <li class="chi-form__item">
      <div class="chi-radio">
        <input type="radio" class="chi-radio__input" name="radio-button-list" id="example__list_opt_1">
        <label class="chi-radio__label" for="example__list_opt_1">Option 1</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-radio">
        <input type="radio" class="chi-radio__input" name="radio-button-list" id="example__list_opt_2">
        <label class="chi-radio__label" for="example__list_opt_2">Option 2</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-radio">
        <input type="radio" class="chi-radio__input" name="radio-button-list" id="example__list_opt_3">
        <label class="chi-radio__label" for="example__list_opt_3">Option 3</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-radio">
        <input type="radio" class="chi-radio__input" name="radio-button-list" id="example__list_opt_4">
        <label class="chi-radio__label" for="example__list_opt_4">Option 4</label>
      </div>
    </li>
    <li class="chi-form__item">
      <div class="chi-radio">
        <input type="radio" class="chi-radio__input" name="radio-button-list" id="example__list_opt_5">
        <label class="chi-radio__label" for="example__list_opt_5">Option 5</label>
      </div>
    </li>
  </ul>
</fieldset>

Web Component

Properties

Property	Attribute	Description	Type	Default
`checked`	`checked`	To render the radiobutton in checked state	`boolean`	undefined
`disabled`	`disabled`	To disable the radiobutton	`boolean`	undefined
`label`	`label`	To provide radiobutton label as a string	`string`	undefined
`name`	`name`	To render the radiobutton input with a respective name attribute	`string`	undefined
`state`	`state`	To indicate the state	`"danger" \| "success" \| "warning"`	undefined

Events

Event	Description	Type
`chiBlur`	Triggered when the radio-button has lost the focus	`CustomEvent<boolean \| string>`
`chiChange`	Triggered when the user selects or deselects the radio-button	`CustomEvent<boolean \| string>`
`chiFocus`	Triggered when the radio-button has the focus	`CustomEvent<boolean \| string>`

Accessibility

Keyboard Navigation

Key	Function
`Tab`	Moves focus to the next focusable element
`Shift + Tab`	Moves focus to the previous focusable element
`Space`	Toggles the selection state of the radio button between checked and unchecked

For comprehensive details on keyboard support for input fields, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Use clear and descriptive labels for radio buttons to help users understand their purpose.
Ensure each radio button has an associated label element using the for attribute to match the id attribute of the radio button.
Assign unique id attributes to each radio button to maintain accessibility and prevent conflicts.
The fieldset surrounds the entire grouping of radio buttons. The legend provides a description for the grouping.
Use the aria-describedby attribute to associate error messages with radio buttons for accessibility.
Ensure that error messages are tagged with unique id attributes and referenced correctly with aria-describedby on corresponding radio buttons.

Find live examples in the A11y style guide.

Roles and attributes

WAI-ARIA provides a grouping role that functions similarly to fieldset and legend.

Role	Element	Usage
`group`	`div`	Identifies the `div` element as a group container for the radio buttons.

Resources

W3 Radio Button Group Example: Information about the radio button accessible behavior.
A11y Style Guide: Gives core recommendations for the accessible radio buttons.
W3C Forms Tutorial: Provides guidance on creating accessible forms.

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)