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.
✅ 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)
Simple checkboxes for individual selections with clear labels:
Choose checkbox sizes based on your layout density and visual hierarchy:
Checkboxes support various states to communicate different conditions to users:
Flexible label and description placement for different layout needs:
Use input groups to organize related checkboxes with shared labels and validation:
Special styling options for use on colored backgrounds or specific visual emphasis:
The checkbox component is designed with accessibility as a core principle:
- Space: Toggle checkbox state
- Enter: Alternative toggle (custom enhancement)
- Tab: Navigate between checkboxes
- Shift + Tab: Navigate backwards
- Proper ARIA labels and descriptions
- State announcements (checked, unchecked, indeterminate)
- Form association and validation messages
- Group labeling for related checkboxes
- Clear focus indicators
- Logical tab order
- Programmatic focus control
- 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
- 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
- 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
import { DapDSCheckbox } from 'dap-design-system'
import { DapDSCheckboxReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSCheckbox } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
indeterminate | boolean | false | Whether the checkbox is indeterminate |
preventDefault | boolean | false | Whether the checkbox should prevent the default action |
border | boolean | false | This sets up border around the checkbox, when true. |
readonly | boolean | false | Whether the checkbox is readonly (cannot be changed but value is submitted with form). |
type | 'normal', 'background' | 'normal' | The type of the checkbox |
feedbackId | feedback-${DapDSCheckbox.nextId}-${uniqueSuffix} | ||
name | string | The name of the checkbox. | |
value | string | The value of the checkbox. | |
checked | boolean | Whether the checkbox is checked. | |
label | string | The label of the checkbox. | |
description | string | The description of the checkbox. | |
disabled | boolean | Whether the checkbox is disabled. | |
required | boolean | Whether the checkbox is required. | |
size | 'xs', 'sm' , 'lg' | The size of the checkbox. Default is 'sm'. | |
sizeMap | string | Responsive size map (e.g. "md:lg"). | |
labelPlacement | 'left', 'right' | The placement of the label. | |
descriptionPlacement | 'top', 'bottom' | The placement of the description. | |
subtle | boolean | The weight of the label. | |
feedback | string | The feedback of the checkbox. | |
feedbackType | 'negative', 'positive' , 'warning' | The feedback type of the checkbox. | |
invalid | boolean | The invalid state of the checkbox. | |
optional | boolean | The optional state of the checkbox. | |
optionalLabel | string | The optional label of the checkbox. |
No slots available.
| Event Name | Description | Type |
|---|---|---|
dds-change | Fired when the checkbox is checked or unchecked. | {checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean, type: 'checkbox' } |
dds-blur | Emitted when the checkbox loses focus. | {void } |
dds-focus | Emitted when the checkbox gains focus. | {void } |
dds-input | Emitted when the checkbox receives input. | {checked: boolean, indeterminate: boolean, value: string, disabled: boolean, readonly: boolean } |
| Part Name | Description |
|---|---|
base | The main checkbox container. |
label | The label of the checkbox. |
input | The input of the checkbox. |
control | The control of the checkbox. |
icon | The icon of the checkbox. |
icon-base | The base icon container. |
label-container | The label container of the checkbox. |
description | The description of the checkbox. |
readonly | The readonly state of the checkbox. |
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.
| Property Name | Description |
|---|---|
--dds-checkbox-size | The size of the checkbox. (default: var(--dds-spacing-500)) |
--dds-checkbox-border-width | The border width of the checkbox. (default: var(--dds-border-width-large)) |
--dds-checkbox-border-radius | The border radius of the checkbox. (default: var(--dds-radius-small)) |
--dds-checkbox-border-color | The border color of the checkbox. (default: var(--dds-border-neutral-base)) |
--dds-checkbox-background-color | The background color of the checkbox. (default: transparent) |
--dds-checkbox-icon-color | The color of the checkbox icon. (default: var(--dds-button-primary-icon-enabled)) |
--dds-checkbox-hover-border-color | The border color when hovering over the checkbox. (default: var(--dds-border-neutral-medium)) |
--dds-checkbox-hover-background-color | The background color when hovering over the checkbox. (default: var(--dds-background-neutral-medium)) |
--dds-checkbox-active-border-color | The border color when the checkbox is active. (default: var(--dds-border-neutral-strong)) |
--dds-checkbox-active-background-color | The background color when the checkbox is active. (default: var(--dds-background-neutral-strong)) |
--dds-checkbox-checked-border-color | The border color when the checkbox is checked. (default: var(--dds-background-brand-base-inverted)) |
--dds-checkbox-checked-background-color | The background color when the checkbox is checked. (default: var(--dds-background-brand-base-inverted)) |
--dds-checkbox-checked-hover-border-color | The border color when hovering over a checked checkbox. (default: var(--dds-background-brand-medium-inverted)) |
--dds-checkbox-checked-hover-background-color | The background color when hovering over a checked checkbox. (default: var(--dds-background-brand-medium-inverted)) |
--dds-checkbox-checked-active-border-color | The border color when a checked checkbox is active. (default: var(--dds-background-brand-strong-inverted)) |
--dds-checkbox-checked-active-background-color | The background color when a checked checkbox is active. (default: var(--dds-background-brand-strong-inverted)) |
--dds-checkbox-invalid-border-color | The border color when the checkbox is invalid. (default: var(--dds-border-negative-base)) |
--dds-checkbox-invalid-background-color | The background color when the checkbox is invalid. (default: var(--dds-background-negative-base)) |
--dds-checkbox-invalid-hover-border-color | The border color when hovering over an invalid checkbox. (default: var(--dds-border-negative-medium)) |
--dds-checkbox-invalid-hover-background-color | The background color when hovering over an invalid checkbox. (default: var(--dds-background-negative-medium)) |
--dds-checkbox-invalid-active-border-color | The border color when an invalid checkbox is active. (default: var(--dds-border-negative-strong)) |
--dds-checkbox-invalid-active-background-color | The background color when an invalid checkbox is active. (default: var(--dds-background-negative-strong)) |
--dds-checkbox-disabled-border-color | The border color when the checkbox is disabled. (default: var(--dds-button-primary-background-disabled)) |
--dds-checkbox-disabled-background-color | The background color when the checkbox is disabled. (default: var(--dds-button-primary-background-disabled)) |
--dds-checkbox-disabled-icon-color | The color of the checkbox icon when disabled. (default: var(--dds-button-primary-icon-disabled)) |
--dds-checkbox-readonly-border-color | The border color when the checkbox is readonly. (default: var(--dds-border-neutral-subtle)) |
--dds-checkbox-readonly-background-color | The background color when the checkbox is readonly. (default: var(--dds-background-neutral-subtle)) |
--dds-checkbox-readonly-icon-color | The color of the checkbox icon when readonly. (default: var(--dds-text-neutral-base)) |
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.
