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

Checkbox button

A checkbox button allows users to select one or more options from a number of choices. Unlike radio buttons, checkboxes can be unselected.

Overview

Standalone checkbox

The checkbox usually appears in a checkbox button. However, standalone checkboxes are used when there is a single selection alongside a large chunk of text, such as a terms and conditions agreement.

Default

Black outline of a white square

Error

Red outline of a white square

Checked

Solid blue square with white checkmark inside, no outline

Checkbox button

Checkbox buttons include a checkbox, label, and optional caption on a clickable surface.

Default

White rectangle with a gray outline, with a dark gray unchecked checkbox and black text label inside

Light blue rectangle with a gray outline, with checked checkbox and black text label inside

Hover

Light blue rectangle with a gray outline, with a black unchecked checkbox and black text label inside

Light blue rectangle with a gray outline, with a dark blue checked checkbox and black text label inside

Focus

A dashed line around the default unchecked checkbox button

A dashed line around the default checked checkbox button

Disabled

Light gray rectangle with a gray outline, with a dark grey unchecked checkbox and dark grey text label inside

Light gray rectangle with a gray outline, with a dark grey square with a dark gray checkmark and dark grey text label inside

Checkbox button group

Checkbox buttons usually appear in groups of two or more, accompanied by a title and optional subtitle.

Default

Checkbox group title is black text, subtitle text is smaller in light gray font, followed by eight checkbox buttons stacked vertically

Error

Light red rectangle includes the checkbox group title, subtitle text, added dark red information icon with black text reading Why is there an error and how to fix it, and checkbox buttons. Checkbox buttons background is an even lighter red but the checkboxes are still white.

Usage context

When to use

Use checkbox buttons when the user may select one or more options from a group. You may also use a checkbox for a single choice that may be selected or unselected, such as agreeing that you have read the terms and conditions.

Checkboxes are useful for:

  • “Select all that apply” questions in forms
  • Filters
  • Toggling between selected and unselected states

When to use something else

Don’t use a checkbox button when the user may only select one option (use a radio button instead)

Usage guidelines

Checkbox 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.

  • NYC mobile app for the Department of Social Services, Do any of these apply to you? Select all that apply. You may also leave this section blank. Student with supporting text of: Currently enrolled full-time in high school or college, has been checked. Active military with supporting text of: Currently serving in the U.S. Armed Forces, National Guard, or Reserves. Veteran with supporting text of: Served in the U.S. Armed Forces, National Guard, or Reserves.
  • NYC mobile app for the Department of Social Services, Select the days of the week that you work. Select all that apply. Unchecked checkbox buttons for each weekday, starting with Monday

You can use the standalone checkbox when you have a single selection alongside a long string of text, such as a terms and conditions agreement.

Checked checkbox to the left of: By checking this box, I state that I have read and understood the terms and conditions.

When there is an error with checkbox buttons, write the error message below the question.

  • Example of correct usage of the error state for checkbox button group.
  • Another example of correct usage of the error state for checkbox button group.

When there is an error with a standalone checkbox, style your container with the “error” surface color, and use the error summary component on the page.

  • nyc.gov mobile portrait view with an error summary component at the top of the page below the mobile navigation controls. There is 1 error on this page, above the Persistent cookies, heading and a bulleted list about web cookies.
  • nyc.gov mobile portrait view showing text followed by a standalone Error checkbox for By checking this box, I state that I have read and understood the terms and conditions and agree, with a light red background followed by a Submit button.

Standalone Checkbox

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

  • Legend element (optional)
  • Checkbox input element
  • Label element: After the checkbox input
This code is for reference only. The library is currently in beta. Check back for future releases.
Default
Long text
Error 
<div class="code-examples">

  <div>
    <legend>Default</legend>
    <div class="nyc-field">
      <input id="checkbox-default" type="checkbox" name="checkbox-default"/>
      <label for="checkbox-default">Default standalone checkbox</label>
    </div>
  </div>

  <div>
    <legend>Long text</legend>
    <div class="nyc-field">
      <input id="checkbox-long-text" type="checkbox" name="checkbox-long-text"/>
      <label for="checkbox-long-text">Long string of text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque vitae urna ac neque posuere fringilla.</label>
    </div>
  </div>

  <div>
    <legend>Error</legend>
    <div class="nyc-field nyc-field--error">
      <input id="checkbox-error" type="checkbox" name="checkbox-error"/>
      <label for="checkbox-error">Standalone checkbox</label>
    </div>
  </div>
    
</div>

Checkbox button

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

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

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

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

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

Checkbox button group

The Checkbox 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 checkboxes.
  • Multiple Checkbox 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 checkbox button elements.
  • Subtitle element (optional): .subtitle: Provides additional context for the dropdown. This should be placed between the label and checkbox 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="checkbox" name="default-group-1"/> Label 1
    </label>
    <label>
      <input type="checkbox" name="default-group-2"/> Label 2
    </label>
    <label>
      <input type="checkbox" name="default-group-3"/> 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="checkbox" name="error-group-1"/> Label 1
    </label>
    <label>
      <input type="checkbox" name="error-group-2"/> Label 2
    </label>
    <label>
      <input type="checkbox" name="error-group-3"/> Label 3
    </label>
  </div>

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