Checkbox | NDS - Vanilla National Design System

Single Checkbox

Standalone checkbox with label and optional description

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 });

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

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