Component contract

checkbox

Native <input type="checkbox"> wrapped as a design-system custom element — checked/indeterminate props forward to the DOM, dsChange emits the new boolean state. Keeps the browser's default checkbox rendering to preserve AT and forced-color-mode behavior.

Version: v1.0.0

Props

Name	Type	Values	Default
checked	boolean	—	false
indeterminate	boolean	—	false
name	string	—	—
value	string	—	—
disabled	boolean	—	false
required	boolean	—	false
invalid	boolean	—	false
describedBy	string	—	—
label	string	—	—

Events

Name	Payload	Condition
dsChange	boolean	—

native_element: input[type=checkbox]
labeling: aria-label via the label prop (canonical) or ambient <label> wrapper (secondary, browser-computed accessible name).
keyboard: ["Tab focuses","Space toggles the checked state","Enter has no native effect on a checkbox"]
disabled_semantics: native_disabled_attribute
error_semantics: aria-invalid (from `invalid` prop) + aria-describedby (from `describedBy` prop, expected to point at a light-DOM node id containing the error message)
required_semantics: aria-required (from `required` prop)
indeterminate_semantics: forwarded to the native `indeterminate` DOM property (not an attribute, not part of the form value); cleared on the next user toggle. This uses the browser's native mechanism rather than a scratch-built ARIA tri-state checkbox, so AT reports 'mixed' via the native path.
rendering_notes: The component intentionally does NOT set `appearance: none` on the native checkbox. Keeping the browser's default rendering preserves the OS/browser accessibility rendering that assistive tech and forced-color modes rely on. A themed checkbox visual is a future decision once the DS commits to a design that still passes 3:1 non-text contrast in every theme and forced-color mode.
notes: label prop is REQUIRED for WCAG conformance — a checkbox with no accessible name is an axe `label` violation. Consumers can also wrap ds-checkbox in a light-DOM <label> for the ambient text-adjacent pattern.

Raw validated JSON

{
  "name": "checkbox",
  "version": "1.0.0",
  "props": {
    "checked": {
      "type": "boolean",
      "default": false
    },
    "indeterminate": {
      "type": "boolean",
      "default": false
    },
    "name": {
      "type": "string"
    },
    "value": {
      "type": "string"
    },
    "disabled": {
      "type": "boolean",
      "default": false
    },
    "required": {
      "type": "boolean",
      "default": false
    },
    "invalid": {
      "type": "boolean",
      "default": false
    },
    "describedBy": {
      "type": "string"
    },
    "label": {
      "type": "string"
    }
  },
  "events": {
    "dsChange": {
      "payload": "boolean"
    }
  },
  "tokens_used": {},
  "a11y": {
    "native_element": "input[type=checkbox]",
    "labeling": "aria-label via the label prop (canonical) or ambient <label> wrapper (secondary, browser-computed accessible name).",
    "keyboard": [
      "Tab focuses",
      "Space toggles the checked state",
      "Enter has no native effect on a checkbox"
    ],
    "disabled_semantics": "native_disabled_attribute",
    "error_semantics": "aria-invalid (from `invalid` prop) + aria-describedby (from `describedBy` prop, expected to point at a light-DOM node id containing the error message)",
    "required_semantics": "aria-required (from `required` prop)",
    "indeterminate_semantics": "forwarded to the native `indeterminate` DOM property (not an attribute, not part of the form value); cleared on the next user toggle. This uses the browser's native mechanism rather than a scratch-built ARIA tri-state checkbox, so AT reports 'mixed' via the native path.",
    "rendering_notes": "The component intentionally does NOT set `appearance: none` on the native checkbox. Keeping the browser's default rendering preserves the OS/browser accessibility rendering that assistive tech and forced-color modes rely on. A themed checkbox visual is a future decision once the DS commits to a design that still passes 3:1 non-text contrast in every theme and forced-color mode.",
    "notes": "label prop is REQUIRED for WCAG conformance — a checkbox with no accessible name is an axe `label` violation. Consumers can also wrap ds-checkbox in a light-DOM <label> for the ambient text-adjacent pattern."
  }
}

Props

Events

Accessibility