Checkbox - National Design System

Added in v1.0.0 Updated in v1.1.0

Multi-selection input controls with clear visual states and accessibility support

Single Checkbox

Standalone checkbox with label and optional description


<div class="nds-form-container nds-check-container" data-required>
  <div class="nds-form-header" data-feedback-target>
    <label for="checkbox-single">
      <span class="nds-label">I agree to the terms and conditions</span>
      <span class="nds-info">You must accept our terms to continue</span>
    </label>
  </div>
  <div class="nds-form-control">
    <input type="checkbox" id="checkbox-single" name="agreement" value="accepted" class="nds-check" required>
  </div>
</div>

Checkbox Group

Multiple checkboxes with shared validation using min/max selection constraints

Select 2-4 interests

Technology

Sports

Entertainment

Education

Travel

Food


<fieldset class="nds-form-group nds-check-group" data-min-checked="2" data-max-checked="4">
  <legend class="nds-label">Select 2-4 interests</legend>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox1">
        <span class="nds-label">Technology</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox1" name="interests" value="technology" class="nds-check">
    </div>
  </div>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox2">
        <span class="nds-label">Sports</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox2" name="interests" value="sports" class="nds-check">
    </div>
  </div>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox3">
        <span class="nds-label">Entertainment</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox3" name="interests" value="entertainment" class="nds-check">
    </div>
  </div>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox4">
        <span class="nds-label">Education</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox4" name="interests" value="education" class="nds-check">
    </div>
  </div>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox5">
        <span class="nds-label">Travel</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox5" name="interests" value="travel" class="nds-check">
    </div>
  </div>
  <div class="nds-form-container nds-check-container">
    <div class="nds-form-header">
      <label for="checkbox6">
        <span class="nds-label">Food</span>
      </label>
    </div>
    <div class="nds-form-control">
      <input type="checkbox" id="checkbox6" name="interests" value="food" class="nds-check">
    </div>
  </div>
  <div class="nds-form-footer" data-feedback-target hidden></div>
</fieldset>

Built-in Features

What you get out of the box with zero configuration

Form Integration

Auto-initializes with the forms system. Two-way binding syncs disabled and required states between inputs and containers.

Indeterminate State

Set via NDS.Forms.setIndeterminate(). Auto-clears on user click. Fires nds:indeterminateChange event with detail.indeterminate boolean.

Group Validation

Min/max constraints with data-min-checked and data-max-checked. Auto-revalidates on change once an error is shown. Call NDS.Forms.clearStatus() to reset.

Responsive Layout

Column layout by default, row layout with nds-rowView class. Gaps adjust on mobile for touch-friendly spacing.

Usage Guidelines

When and how to use checkboxes effectively

When to Use

Multiple selections from a list of options
Binary choices like accepting terms or toggling a setting
Use radio buttons when only one selection is allowed
Use switches for instant on/off actions without form submission
Keep groups to 7 or fewer options. For longer lists, consider a multi-select dropdown
Use indeterminate state for "select all" parent checkboxes that partially control child selections

JavaScript API


// Set indeterminate state on a checkbox
var checkbox = document.querySelector('#my-checkbox');
NDS.Forms.setIndeterminate(checkbox, true);

// Listen for indeterminate changes
checkbox.addEventListener('nds:indeterminateChange', function(e) {
  console.log('Indeterminate:', e.detail.indeterminate);
});

// Validate a checkbox group manually
var group = document.querySelector('.nds-check-group');
var result = NDS.Forms.validateCheckboxGroup(group);
// result: { valid: false, checked: 1, min: 2, max: 4, message: '...' }

// Validate without showing feedback
NDS.Forms.validateCheckboxGroup(group, { showMessage: false });

// Attach change-listener validation to a group (called automatically at init)
NDS.Forms.initCheckboxGroupValidation(group);

// Clear validation status
NDS.Forms.clearStatus(group);

Data Attributes

Attribute	Element	Description
`data-state~="indeterminate"`	`.nds-form-container`	Stamped by `NDS.Forms.setIndeterminate()` when the checkbox is indeterminate; removed when cleared
`data-state~="disabled"`	`.nds-form-container`, `.nds-check-group`	Propagates disabled styling to all child inputs
`data-state~="readonly"`	`.nds-form-container`	Renders the checkbox tile as read-only: border only, no fill
`data-required`	`.nds-form-container`, `.nds-check-group`	Marks a single checkbox or group as required on form submit
`data-min-checked`	`.nds-check-group`	Minimum number of checkboxes that must be selected
`data-max-checked`	`.nds-check-group`	Maximum number of checkboxes that may be selected
`data-error-message`	`.nds-check-group`	Overrides the default validation error message shown below the group

CSS Custom Properties

Property	Default	Description
`--checkbox-tile-bg`	`--background-default`	Fill color of the checkbox tile. Override inline to tint a single checkbox
`--checkbox-tile-border`	`--controls-border`	Box-shadow ring color around the tile
`--checkbox-glyph-bg`	`--background-default`	Color of the checkmark or dash glyph painted inside the tile
`--nds-input-size`	`16px`	Size of the checkbox control. Set by size modifiers: `nds-md` = 20px, `nds-lg` = 24px. Override inline for a custom size

Validation Attributes

Add data-required to a single checkbox container to make it mandatory before form submission
Add data-required to a group to require at least one selection
Use data-min-checked="2" on a group to enforce a minimum number of selections
Use data-max-checked="4" on a group to cap the maximum number of selections
Combine both for a range constraint (e.g. "select 2 to 4 options")
Add data-error-message on the group to override the default validation message
Place a nds-form-footer with data-feedback-target inside the group for dynamic feedback placement

Last Modified Date: 28/06/2026 - 01:27 PM