Checkbox

The <nys-checkbox> component is a form input for users to select options (zero, one, or multiple) from a collection of choices. It provides users with the ability to toggle a binary state (checked/unchecked). Indeterminate states are not (currently) supported.

Optional: <nys-checkboxgroup> can be used to group multiple checkboxes so they function as a single form control.

Copy Code
<nys-checkboxgroup label="Select your favorite New York landmarks" description="Last year's winner is not eligible to win again.">
      <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks" checked></nys-checkbox>
      <nys-checkbox name="landmarks" value="finger-lakes" label="Finger Lakes" checked></nys-checkbox>
      <nys-checkbox name="landmarks" value="catskills" label="Catskills"></nys-checkbox>
      <nys-checkbox name="landmarks" value="niagara-falls" label="Niagara Falls"></nys-checkbox>
      <nys-checkbox name="landmarks" value="coney-island" label="Coney Island"></nys-checkbox>
      <nys-checkbox name="landmarks" value="statue-liberty" label="Statue of Liberty (Last Year's Winner)" description="Disabled as it was the winner of the previous year." disabled></nys-checkbox>
    </nys-checkboxgroup>

Can't use NYS design System web components in your project? Try using the CSS Variables instead.


Options

Checkbox group

The <nys-checkboxgroup> component can be used to group multiple checkboxes, allowing them to function as a single form control. This is useful when you want to allow users to select multiple options from a list.

Copy Code
<nys-checkboxgroup label="Do you attest to the following:" description="By checking below you agree to our terms">
  <nys-checkbox name="legal" label="I have read the terms and conditions." id="terms-conditions" value="terms-conditions"></nys-checkbox>
  <nys-checkbox name="legal" label="I agree to the NDA" id="legal" value="legal"></nys-checkbox>
</nys-checkboxgroup>

Disabled

Copy Code
<nys-checkbox disabled checked label="I agree to the terms and conditions" description="This option is currently unavailable." name="earlyVoting" value="early-voting"></nys-checkbox>

Size

Set the size property of the <nys-checkboxgroup> to have all <nys-checkbox> be the same size. Our current sizes are:

  • sm : Set to 24px in width and height
  • md : The default size. Set to 32px in width and height.
Copy Code
<nys-checkboxgroup label="Select your favorite New York landmarks" description="Choose from the options below" size="sm">
  <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="finger-lakes" label="Finger Lakes" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="catskills" label="Catskills" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="niagara-falls" label="Niagara Falls"></nys-checkbox>
  <nys-checkbox name="landmarks" value="coney-island" label="Coney Island"></nys-checkbox>
  <nys-checkbox name="landmarks" label="Mount Greylock" description="This is disabled because it's not in New York." disabled></nys-checkbox>
</nys-checkboxgroup>

Tile

The tile prop will change the styling of the checkbox to a tile. This is useful when you want a larger clickable area for the user.

  • The tile prop can be applied to the <nys-checkboxgroup> or the <nys-checkbox> component. If applied to the <nys-checkboxgroup>, all checkboxes will be displayed as tiles. If applied to the <nys-checkbox>, only that checkbox will be displayed as a tile.
  • Do not use the tile prop on a checkbox if it is inside a <nys-checkboxgroup>. All checkboxes in a group should be the same size and style.
Copy Code
<nys-checkboxgroup label="Select your favorite New York landmarks" description="Choose from the options below" tile>
  <nys-checkbox name="landmarks" label="Adirondacks" value="adirondacks" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="finger-lakes" label="Finger Lakes" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="catskills" label="Catskills" checked></nys-checkbox>
  <nys-checkbox name="landmarks" value="niagara-falls" label="Niagara Falls"></nys-checkbox>
  <nys-checkbox name="landmarks" value="coney-island" label="Coney Island"></nys-checkbox>
  <nys-checkbox name="landmarks" label="Mount Greylock" description="This is disabled because it's not in New York." disabled></nys-checkbox>
</nys-checkboxgroup>

Required

Set required to make a checkbox or group of checkboxes mandatory. It can be applied to either <nys-checkboxgroup> (no need to add it to individual children) or directly to an individual <nys-checkbox>.

Copy Code
<nys-checkbox
  label="Subscribe to NYS Government Updates"
  description="Get notified via email about important updates and services."
  id="subscribe-checkbox-disabled-checked"
  name="subscribe"
  value="email-updates"
  required
></nys-checkbox>

Optional

Adding the optional prop will add an optional flag to the input.

Copy Code
<nys-checkboxgroup label="Select your favorite New York landmarks" description="Choose from the options below" optional>
  <nys-checkbox name="landmarks" value="adirondacks" label="Adirondacks"></nys-checkbox>
  <nys-checkbox name="landmarks" value="finger-lakes" label="Finger Lakes"></nys-checkbox>
  <nys-checkbox name="landmarks" value="catskills" label="Catskills"></nys-checkbox>
</nys-checkboxgroup>

Error

Set an error message and choose to activate it. Setting errorMessage does not display the message without boolean prop showError.

Errors can be assigned to both <nys-checkboxgroup> and individual <nys-checkbox> components.

Copy Code
<nys-checkboxgroup label="Select your favorite New York landmarks" description="Choose from the options below" showError errorMessage="You must select at least one option to continue.">
  <nys-checkbox name="landmarks" label="Adirondacks" value="adirondacks" ></nys-checkbox>
  <nys-checkbox name="landmarks" value="finger-lakes" label="Finger Lakes" ></nys-checkbox>
  <nys-checkbox name="landmarks" value="catskills" label="Catskills" ></nys-checkbox>
</nys-checkboxgroup>

Slotted Description

When the description requires more complexity than a simple string, use the description slot to hold the text. This allows the developer to include HTML in the description, such as anchors or bold text.

Copy Code
<nys-checkbox label="Subscribe to NYS Government Updates" id="subscribe-updates" name="subscribe" value="email-updates">
  <label slot="description">Read about our <a href="https://www.ny.gov/" target="__blank">previous updates</a></label>
</nys-checkbox>

Usage

When to use this component

  • When collecting binary answers in a form.
  • When obtaining confirmation from users.
  • When allowing users to select multiple options from a list.

When to consider something else

  • Use a toggle when changing the state of a binary input immediately changes the system's state; such as enabling Dark Mode.
  • When users need to select only one option, consider a radio button (1-6 choices) or select (7 or more choices) instead.

Do

  • Use checkboxes for binary decisions (agree/disagree).
  • Use checkboxes for multi-select lists (like selecting interests).

Don't

  • Avoid using when you have more than 10 options to choose from; instead, consider a multiselect dropdown (coming soon).
  • Don’t change the state of one checkbox based on another being clicked.

Accessibility

The <nys-checkbox> component includes the following accessibility-focused features:

  • Proper ARIA roles and attributes to ensure screen readers can interpret the checkbox correctly.
  • Keyboard navigation support, allowing users to toggle the checkbox using the keyboard.
  • Visual focus indicators to help users navigate the component.
  • Include a label property to provide accessible text for screen readers.

Properties

Property Type Component
id String both
name String both
label String both
value String only <nys-checkbox>
checked boolean only <nys-checkbox>
description String both
disabled boolean both
errorMessage String both
optional boolean only <nys-checkboxgroup>
required boolean both
showError boolean both
size "sm" | "md" both
tile boolean both
form String | null both

CSS Variables

There are no existing CSS variables for this component. Explore existing options, or propose a new one with a Component Proposal.


Events

The <nys-checkbox> component emits three custom Javascript events:

  1. nys-change – Fired when the checkbox state changes (checked/unchecked).
  2. nys-focus – Fired when the checkbox gains focus.
  3. nys-blur – Fired when the checkbox loses focus.

Event details

The nys-change event includes a detail object with the following properties:

  • id (string): The id of the checkbox.
  • checked (boolean): Whether the checkbox is currently checked.
  • name (string): The checkbox’s name attribute (useful in forms).
  • value (string): The checkbox’s value attribute.

You can listen to these events using JavaScript:

Copy Code
// Select the checkbox component
const checkbox = document.querySelector('nys-checkbox');
// Listen for the 'nys-change' event
checkbox.addEventListener('nys-change', (event) => {
  const { id, checked, name, value } = event.detail;
  console.log(`Checkbox ${id} changed: checked=${checked}, name=${name}, value=${value}`);
});

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: December 3, 2025