Checkbox Overview

The checkbox component allows users to select one or more options from a set of choices. It's a fundamental form control that provides clear visual feedback for user selections and supports various states including checked, unchecked, indeterminate, and disabled. The component is designed with accessibility in mind, supporting keyboard navigation, screen readers, and proper form integration.

When to Use

✅ Use checkboxes when:

  • Users need to select multiple options from a list
  • Turning features or settings on/off independently
  • Accepting terms, conditions, or agreements
  • Building forms with optional or required selections
  • Creating filter interfaces with multiple criteria
  • Allowing bulk selection operations

❌ Don't use checkboxes for:

  • Single-choice selection (use radio buttons instead)
  • Simple yes/no questions (consider toggle switches)
  • Navigation or action triggers (use buttons)
  • Displaying status without user interaction (use status indicators)
Design system docs Examples Basic Usage

Simple checkboxes for individual selections with clear labels:

<dap-ds-stack direction="column">
<dap-ds-checkbox
  value="option-1"
  label="Enable notifications">
</dap-ds-checkbox>

<dap-ds-checkbox
  value="option-2"
  label="Subscribe to newsletter"
  checked>
</dap-ds-checkbox>

<dap-ds-checkbox
  value="option-3"
  label="Remember my preferences">
</dap-ds-checkbox>
</dap-ds-stack>
Sizes & Scaling

Choose checkbox sizes based on your layout density and visual hierarchy:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Size variations</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      value="xs-option"
      label="Extra small checkbox"
      description="Compact size for dense layouts"
      size="xs">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      value="sm-option"
      label="Small checkbox (default)"
      description="Standard size for most use cases"
      size="sm">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      value="md-option"
      label="Medium checkbox"
      description="Larger size for better accessibility"
      size="md">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      value="lg-option"
      label="Large checkbox"
      description="Prominent size for important selections"
      size="lg">
    </dap-ds-checkbox>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
States & Feedback

Checkboxes support various states to communicate different conditions to users:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Interactive states</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Default unchecked"
      value="state-1">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Checked state"
      value="state-2"
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Indeterminate state"
      value="state-3"
      indeterminate>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Disabled unchecked"
      value="state-4"
      disabled>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Disabled checked"
      value="state-5"
      checked
      disabled>
    </dap-ds-checkbox>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Validation states</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Required checkbox"
      value="validation-1"
      required
      invalid
      feedback="This field is required"
      feedbackType="negative">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Valid selection"
      value="validation-2"
      checked
      feedback="Great choice!"
      feedbackType="positive">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Warning example"
      value="validation-3"
      checked
      feedback="This action cannot be undone"
      feedbackType="warning">
    </dap-ds-checkbox>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Label Positioning & Descriptions

Flexible label and description placement for different layout needs:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Label positioning</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Label on the right (default)"
      value="pos-1"
      description="Description appears below the label">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Label on the left"
      value="pos-2"
      description="Description still follows the label"
      labelPlacement="left">
    </dap-ds-checkbox>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Description placement</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Description below"
      value="desc-1"
      description="This description appears below the label"
      descriptionPlacement="bottom">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Description above"
      value="desc-2"
      description="This description appears above the label"
      descriptionPlacement="top">
    </dap-ds-checkbox>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Checkbox Groups

Use input groups to organize related checkboxes with shared labels and validation:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Settings preferences</dap-ds-typography>
  <dap-ds-input-group
    required
    label="Notification Settings"
    description="Choose which notifications you'd like to receive"
    tooltip="These settings control email and push notifications"
    tooltipAriaLabel="Information about notification settings">
    
    <dap-ds-checkbox
      label="Email notifications"
      description="Receive updates via email"
      value="email-notifications">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Push notifications"
      description="Receive browser push notifications"
      value="push-notifications"
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="SMS notifications"
      description="Receive text message alerts"
      value="sms-notifications">
    </dap-ds-checkbox>
  </dap-ds-input-group>
</div>

<div>
  <dap-ds-typography variant="h4">Form validation example</dap-ds-typography>
  <dap-ds-input-group
    required
    label="Terms and Conditions"
    description="Please review and accept the following"
    feedbackType="negative"
    feedback="You must accept all terms to continue">
    
    <dap-ds-checkbox
      label="I accept the Terms of Service"
      value="terms-service"
      invalid
      required>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="I accept the Privacy Policy"
      value="privacy-policy"
      checked
      required>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="I want to receive marketing communications"
      value="marketing-consent"
      description="Optional - you can change this later in settings">
    </dap-ds-checkbox>
  </dap-ds-input-group>
</div>
</dap-ds-stack>
</>
Background & Border Variants

Special styling options for use on colored backgrounds or specific visual emphasis:

<>
<div style={{ backgroundColor: "#e9edf2", padding: "16px", borderRadius: "8px" }}>
<dap-ds-stack direction="column">
  <dap-ds-typography variant="h4">Background variant</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Background style checkbox"
      description="Better visibility on colored backgrounds"
      value="bg-1"
      type="background">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Background with border"
      description="Enhanced definition with border"
      value="bg-2"
      type="background"
      border
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Regular checkbox on background"
      description="Standard styling for comparison"
      value="bg-3">
    </dap-ds-checkbox>
  </dap-ds-stack>
</dap-ds-stack>
</div>

<div style={{ backgroundColor: "white", padding: "16px", border: "1px solid #e0e0e0", borderRadius: "8px", marginTop: "16px" }}>
<dap-ds-stack direction="column">
  <dap-ds-typography variant="h4">Border emphasis</dap-ds-typography>
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Bordered checkbox"
      description="Added border for visual emphasis"
      value="border-1"
      border>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Bordered and checked"
      description="Border with checked state"
      value="border-2"
      border
      checked>
    </dap-ds-checkbox>
  </dap-ds-stack>
</dap-ds-stack>
</div>
</>
Real-World Patterns User Preferences Form 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h3">Account Preferences</dap-ds-typography>
  
  <dap-ds-input-group
    label="Privacy Settings"
    description="Control how your information is used and shared">
    
    <dap-ds-checkbox
      label="Make my profile public"
      description="Other users can view your profile information"
      value="public-profile">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Allow search engines to index my profile"
      description="Your profile may appear in search results"
      value="search-indexing">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Share activity data for analytics"
      description="Help us improve the service (anonymous data only)"
      value="analytics-sharing"
      checked>
    </dap-ds-checkbox>
  </dap-ds-input-group>

  <dap-ds-input-group
    label="Communication Preferences"
    description="Choose how and when we contact you">
    
    <dap-ds-checkbox
      label="Product updates and announcements"
      description="Important news about new features and changes"
      value="product-updates"
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Weekly digest email"
      description="Summary of your activity and recommendations"
      value="weekly-digest">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Marketing and promotional content"
      description="Special offers, tips, and educational content"
      value="marketing-content">
    </dap-ds-checkbox>
  </dap-ds-input-group>

  <dap-ds-stack direction="row">
    <dap-ds-button>Save Preferences</dap-ds-button>
    <dap-ds-button variant="outline">Cancel</dap-ds-button>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Shopping Cart Features 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h3">Order Options</dap-ds-typography>
  
  <dap-ds-stack direction="column">
    <dap-ds-checkbox
      label="Gift wrapping"
      description="Add special gift wrapping (+$5.99)"
      value="gift-wrapping">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Express shipping"
      description="Delivery within 24 hours (+$12.99)"
      value="express-shipping">
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Insurance coverage"
      description="Protect your order against damage or loss (+$3.99)"
      value="insurance"
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="SMS delivery updates"
      description="Receive text messages about your delivery status"
      value="sms-updates">
    </dap-ds-checkbox>
  </dap-ds-stack>

  <div style={{borderTop: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', paddingTop: 'var(--dds-spacing-400)', marginTop: 'var(--dds-spacing-400)'}}>
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>Total: $127.97</dap-ds-typography>
      <dap-ds-button>Proceed to Checkout</dap-ds-button>
    </dap-ds-stack>
  </div>
</dap-ds-stack>
</div>
Multi-step Form with Validation 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h3">Account Setup - Step 2 of 3</dap-ds-typography>
  
  <dap-ds-input-group
    required
    label="Required Agreements"
    description="Please review and accept the following to continue"
    feedbackType="negative"
    feedback="You must accept all required terms to proceed">
    
    <dap-ds-checkbox
      label="Terms of Service"
      description="I have read and accept the Terms of Service"
      value="terms-service"
      required
      invalid>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Privacy Policy"
      description="I understand how my data will be processed"
      value="privacy-policy"
      required
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Age Verification"
      description="I confirm that I am at least 18 years old"
      value="age-verification"
      required
      checked>
    </dap-ds-checkbox>
  </dap-ds-input-group>

  <dap-ds-input-group
    label="Optional Preferences"
    description="These can be changed later in your account settings">
    
    <dap-ds-checkbox
      label="Email notifications"
      description="Receive important updates via email"
      value="email-notifications"
      checked>
    </dap-ds-checkbox>

    <dap-ds-checkbox
      label="Newsletter subscription"
      description="Get weekly tips and product updates"
      value="newsletter">
    </dap-ds-checkbox>
  </dap-ds-input-group>

  <dap-ds-stack direction="row" justify="space-between">
    <dap-ds-button variant="outline">Previous Step</dap-ds-button>
    <dap-ds-button disabled>Continue</dap-ds-button>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Accessibility & Keyboard Navigation

The checkbox component is designed with accessibility as a core principle:

Keyboard Support
  • Space: Toggle checkbox state
  • Enter: Alternative toggle (custom enhancement)
  • Tab: Navigate between checkboxes
  • Shift + Tab: Navigate backwards
Screen Reader Support
  • Proper ARIA labels and descriptions
  • State announcements (checked, unchecked, indeterminate)
  • Form association and validation messages
  • Group labeling for related checkboxes
Focus Management
  • Clear focus indicators
  • Logical tab order
  • Programmatic focus control
<dap-ds-stack direction="column">
<dap-ds-typography variant="h4">Accessibility Examples</dap-ds-typography>

<dap-ds-checkbox
  label="Accessible checkbox"
  description="Try navigating with Tab and toggling with Space"
  value="accessible-1">
</dap-ds-checkbox>

<dap-ds-checkbox
  label="Indeterminate with screen reader support"
  description="Screen readers announce this as 'mixed' state"
  value="accessible-2"
  indeterminate>
</dap-ds-checkbox>

<dap-ds-checkbox
  label="Required field with validation"
  description="Screen readers announce validation messages"
  value="accessible-3"
  required
  invalid
  feedback="This field is required for form submission"
  feedbackType="negative">
</dap-ds-checkbox>
</dap-ds-stack>
Best Practices Form Integration
  • Always provide clear, descriptive labels
  • Use descriptions for additional context
  • Group related checkboxes with dap-ds-input-group
  • Implement proper validation feedback
  • Consider the indeterminate state for parent-child relationships
Visual Design
  • Maintain consistent sizing within forms
  • Use background variants on colored surfaces
  • Consider border emphasis for important selections
  • Provide sufficient color contrast
  • Test with different themes and accessibility settings
User Experience
  • Use progressive disclosure for complex option sets
  • Provide clear feedback for validation states
  • Consider the cognitive load of multiple options
  • Make optional vs. required selections clear
  • Test with real users and assistive technologies
Importing 
import { DapDSCheckbox } from 'dap-design-system'
Importing React 
import { DapDSCheckboxReact } from 'dap-design-system/react'
Tree-Shakeable Imports

For optimal bundle sizes, use the tree-shakeable import syntax:

import { DapDSCheckbox } from 'dap-design-system/components'
Attributes
PropertyTypeDefaultDescription
indeterminatebooleanfalseWhether the checkbox is indeterminate
preventDefaultbooleanfalseWhether the checkbox should prevent the default action
borderbooleanfalseThis sets up border around the checkbox, when true.
readonlybooleanfalseWhether the checkbox is readonly (cannot be changed but value is submitted with form).
type'normal', 'background''normal'The type of the checkbox
namestringThe name of the checkbox.
valuestringThe value of the checkbox.
checkedbooleanWhether the checkbox is checked.
labelstringThe label of the checkbox.
descriptionstringThe description of the checkbox.
disabledbooleanWhether the checkbox is disabled.
requiredbooleanWhether the checkbox is required.
size'xs', 'sm' , 'lg'The size of the checkbox. Default is 'sm'.
labelPlacement'left', 'right'The placement of the label.
descriptionPlacement'top', 'bottom'The placement of the description.
subtlebooleanThe weight of the label.
feedbackstringThe feedback of the checkbox.
feedbackType'negative', 'positive' , 'warning'The feedback type of the checkbox.
invalidbooleanThe invalid state of the checkbox.
optionalbooleanThe optional state of the checkbox.
optionalLabelstringThe optional label of the checkbox.
Slots

No slots available.

Events
Event NameDescriptionType
dds-changeFired when the checkbox is checked or unchecked.{checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean, type: 'checkbox' }
dds-blurEmitted when the checkbox loses focus.{void }
dds-focusEmitted when the checkbox gains focus.{void }
dds-inputEmitted when the checkbox receives input.{checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean }
CSS Parts
Part NameDescription
baseThe main checkbox container.
labelThe label of the checkbox.
inputThe input of the checkbox.
controlThe control of the checkbox.
iconThe icon of the checkbox.
label-containerThe label container of the checkbox.
descriptionThe description of the checkbox.
readonlyThe readonly state of the checkbox.
How to Use CSS Parts

You can style CSS parts using the ::part() pseudo-element selector:

/* Target a specific part */
.my-custom-dap-ds-checkbox::part(base) {
  /* Your custom styles */
}

/* Target multiple parts */
.my-custom-dap-ds-checkbox::part(base),
.my-custom-dap-ds-checkbox::part(label) {
  /* Shared styles */
}

Example usage:

<dap-ds-checkbox class="my-custom-dap-ds-checkbox">
  Checkbox
</dap-ds-checkbox>

.my-custom-dap-ds-checkbox::part(base) {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.

 CSS Custom Properties
Property NameDescription
--dds-checkbox-sizeThe size of the checkbox. Default is `var(--dds-spacing-500)`.
--dds-checkbox-border-widthThe border width of the checkbox. Default is `var(--dds-border-width-large)`.
--dds-checkbox-border-radiusThe border radius of the checkbox. Default is `var(--dds-radius-small)`.
--dds-checkbox-border-colorThe border color of the checkbox. Default is `var(--dds-border-neutral-base)`.
--dds-checkbox-background-colorThe background color of the checkbox. Default is `transparent`.
--dds-checkbox-icon-colorThe color of the checkbox icon. Default is `var(--dds-button-primary-icon-enabled)`.
--dds-checkbox-hover-border-colorThe border color when hovering over the checkbox. Default is `var(--dds-border-neutral-medium)`.
--dds-checkbox-hover-background-colorThe background color when hovering over the checkbox. Default is `var(--dds-background-neutral-medium)`.
--dds-checkbox-active-border-colorThe border color when the checkbox is active. Default is `var(--dds-border-neutral-strong)`.
--dds-checkbox-active-background-colorThe background color when the checkbox is active. Default is `var(--dds-background-neutral-strong)`.
--dds-checkbox-checked-border-colorThe border color when the checkbox is checked. Default is `var(--dds-background-brand-base-inverted)`.
--dds-checkbox-checked-background-colorThe background color when the checkbox is checked. Default is `var(--dds-background-brand-base-inverted)`.
--dds-checkbox-checked-hover-border-colorThe border color when hovering over a checked checkbox. Default is `var(--dds-background-brand-medium-inverted)`.
--dds-checkbox-checked-hover-background-colorThe background color when hovering over a checked checkbox. Default is `var(--dds-background-brand-medium-inverted)`.
--dds-checkbox-checked-active-border-colorThe border color when a checked checkbox is active. Default is `var(--dds-background-brand-strong-inverted)`.
--dds-checkbox-checked-active-background-colorThe background color when a checked checkbox is active. Default is `var(--dds-background-brand-strong-inverted)`.
--dds-checkbox-invalid-border-colorThe border color when the checkbox is invalid. Default is `var(--dds-border-negative-base)`.
--dds-checkbox-invalid-background-colorThe background color when the checkbox is invalid. Default is `var(--dds-background-negative-base)`.
--dds-checkbox-invalid-hover-border-colorThe border color when hovering over an invalid checkbox. Default is `var(--dds-border-negative-medium)`.
--dds-checkbox-invalid-hover-background-colorThe background color when hovering over an invalid checkbox. Default is `var(--dds-background-negative-medium)`.
--dds-checkbox-invalid-active-border-colorThe border color when an invalid checkbox is active. Default is `var(--dds-border-negative-strong)`.
--dds-checkbox-invalid-active-background-colorThe background color when an invalid checkbox is active. Default is `var(--dds-background-negative-strong)`.
--dds-checkbox-disabled-border-colorThe border color when the checkbox is disabled. Default is `var(--dds-button-primary-background-disabled)`.
--dds-checkbox-disabled-background-colorThe background color when the checkbox is disabled. Default is `var(--dds-button-primary-background-disabled)`.
--dds-checkbox-disabled-icon-colorThe color of the checkbox icon when disabled. Default is `var(--dds-button-primary-icon-disabled)`.
--dds-checkbox-readonly-border-colorThe border color when the checkbox is readonly. Default is `var(--dds-border-neutral-subtle)`.
--dds-checkbox-readonly-background-colorThe background color when the checkbox is readonly. Default is `var(--dds-background-neutral-subtle)`.
--dds-checkbox-readonly-icon-colorThe color of the checkbox icon when readonly. Default is `var(--dds-text-neutral-base)`.
How to Use CSS Custom Properties

CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:

Method 1: Inline styles (Quick customization)

<dap-ds-checkbox
  style="--dds-checkbox-size: value; --dds-checkbox-border-width: value;">
  Checkbox
</dap-ds-checkbox>

Method 2: CSS classes (Reusable styles)

.my-custom-dap-ds-checkbox {
  --dds-checkbox-size: value;
  --dds-checkbox-border-width: value;
  --dds-checkbox-border-radius: value;
}

<dap-ds-checkbox class="my-custom-dap-ds-checkbox">
  Checkbox
</dap-ds-checkbox>

Method 3: Global theme customization

/* Apply to all instances */
dap-ds-checkbox {
  --dds-checkbox-size: value;
  --dds-checkbox-border-width: value;
}

CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.