Skip to main content
Official website. How you know

Official websites use .gov

A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS

A lock or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Digital Design System

Radio button

A radio button allows users to select only one option from a number of choices.

Overview

Radio button

Radio buttons include a radio, label, and optional caption on a clickable surface.

Default

The unselected radio button is a white rounded rectangle with a gray outline. Inside is a white circle with a gray outline alongside a text label.

The selected radio button is a light blue rounded rectangle with a gray outline. Inside is a dark blue circle with a light blue center alongside a text label.

Hover

In the hover state, the unselected radio button background turns light blue.

In the hover state, the selected radio button's circle changes from blue to dark blue.

Focus

In the focus state, the entire component is surrounded by a dashed line.

In the focus state, the entire component is surrounded by a dashed line.

Disabled

In the disabled unselected state, the background changes to light gray.

In the selected disabled state, the background changes to light gray and the circle changes to dark gray with a light gray center.

Radio button group

Radio buttons always appear in a group of two or more, accompanied by a title and optional subtitle.

Default

An example of a radio button group. It has a large title, a smaller subtitle in light gray font, followed by four radio buttons stacked vertically.

Error

In the error state, the background of the entire container that includes the title, subtitle, and radio buttons turns red. The red inside the radio buttons is lighter than the red of the container. An error message appears below the subtitle text. The placeholder message is "Why is there an error and how to fix it." To the left of this message there is a red icon of an exclamation point in a circle.

Usage context

When to use

Use radio buttons when the user must select one option from a group of mutually exclusive options.

When to use something else

Don’t use a radio button in the following situations. Use a checkbox button instead.

  • When the user may select multiple options
  • When the user may select no options
  • When an option may be selected and then unselected
  • When there is only one option, such as agreeing that you have read the terms and conditions

Usage guidelines

Radio button labels should make it as clear as possible what the user is selecting. If you need to add more context, you may add supporting text.

Mobile nyc.gov screenshot demonstrating radio buttons with supporting text to add context. The question is "Describe the problem. Select one." There are two radio buttons visible, each with a label and supporting text. They read "Partial access" supporting text: "I can still get in and out of my driveway" and "No access" supporting text: "My driveway is completely blocked"

Radio button

The radio button can be utilized with an nyc-field class container, with the following items:

  • Label element: This acts as the button
  • Radio input element: Contained within the label
This code is for reference only. The library is currently in beta. Check back for future releases.
Default
Checked
Disabled
Disabled&Checked 
<div class="code-examples">

  <div class="nyc-field">
    <legend>Default</legend>
    <label>
      <input type="radio" name="radio-default"/> Label
    </label>
  </div>

  <div class="nyc-field">
    <legend>Checked</legend>
    <label>
      <input type="radio" name="radio-checked" checked/> Label
    </label>
  </div>

  <div class="nyc-field">
    <legend>Disabled</legend>
    <label>
      <input type="radio" name="radio-disabled" disabled/> Label
    </label>
  </div>

  <div class="nyc-field">
    <legend>Disabled&Checked</legend>
    <label>
      <input type="radio" name="radio-disabled-checked" disabled checked/> Label
    </label>
  </div>
    
</div>

Radio button group

The Radio button group can be utilized with an nyc-field class container, with the following items:

  • Legend element: This acts as the title for the group of radio buttons.
  • Multiple Radio button components: As described above, but without individual nyc-field containers
  • Error element (optional): .error-message: Provides error messaging for the group. This should be placed after the legend and subtitle, and before the radio button elements.
  • Subtitle element (optional): .subtitle: Provides additional context for the dropdown. This should be placed between the label and radio button elements.
This code is for reference only. The library is currently in beta. Check back for future releases.
Default Subtitle text
Error Subtitle text
This field is required.
Supporting Text Subtitle text 
<div class="code-examples">

  <div class="nyc-field">
    <legend>Default</legend>
    <span class="subtitle">Subtitle text</span>
    <label>
      <input type="radio" name="default-group"/> Label 1
    </label>
    <label>
      <input type="radio" name="default-group"/> Label 2
    </label>
    <label>
      <input type="radio" name="default-group"/> Label 3
    </label>
  </div>

  <div class="nyc-field nyc-field--error">
    <legend>Error</legend>
    <span class="subtitle">Subtitle text</span>
    <div class="error-message"><i class="i-ph:warning-circle-bold"></i>This field is required.</div>
    <label>
      <input type="radio" name="error-group"/> Label 1
    </label>
    <label>
      <input type="radio" name="error-group"/> Label 2
    </label>
    <label>
      <input type="radio" name="error-group"/> Label 3
    </label>
  </div>

  <div class="nyc-field">
    <legend>Supporting Text</legend>
    <span class="subtitle">Subtitle text</span>
    <label>
      <input type="radio" name="supporting-text-group"/>
      <div>
        <span>Label 1</span>
        <span class="subtitle">Supporting text</span>
      </div>
    </label>
    <label>
      <input type="radio" name="supporting-text-group"/>
      <div>
        <span>Label 2</span>
        <span class="subtitle">Supporting text</span>
      </div>
    </label>
    <label>
      <input type="radio" name="supporting-text-group"/>
      <div>
        <span>Label 3</span>
        <span class="subtitle">Supporting text</span>
      </div>
    </label>
  </div>
    
</div>