ki-checkbox
@kimen/elements/ki-checkbox- Source
- Agent reference
A form-associated checkbox for selecting independent options that a form submits later. Always provide a visible label in the default slot.
<ki-checkbox name="tos" required>I accept the terms</ki-checkbox>Examples
Section titled “Examples”States
Section titled “States”Boolean attributes use presence semantics: omit checked to express
unchecked — never write checked="false".
<ki-checkbox>Unchecked</ki-checkbox><ki-checkbox checked>Checked</ki-checkbox><ki-checkbox disabled>Disabled</ki-checkbox>Indeterminate
Section titled “Indeterminate”A “select all” parent presents partial selection with indeterminate:
<ki-checkbox indeterminate>Select all (2 of 5 selected)</ki-checkbox>In a form
Section titled “In a form”Checkboxes contribute name/value to FormData and honor required
through native constraint validation:
<form onsubmit="event.preventDefault()"><ki-checkbox name="newsletter" value="weekly">Weekly digest</ki-checkbox><ki-checkbox name="tos" required>I accept the terms</ki-checkbox><ki-button variant="primary">Sign up</ki-button></form>API reference
Section titled “API reference”When to use: selecting one or more independent options that a form submits later, including a "select all" parent that presents partial selection with indeterminate. Always provide a visible label in the default slot.
When not to use: a single mutually exclusive choice, an immediate on/off effect, triggering an action, unlabeled/icon-only usage, or checked="false" to mean unchecked. Boolean attributes use presence semantics; omit checked to express unchecked.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
checked | checked | boolean | false | Live binary selection state. User activation by pointer, slotted label or Space toggles it with native checkbox parity and emits composed input before composed change. Boolean presence semantics apply: checked="false" still renders checked; omit the attribute to express unchecked. Programmatic assignment is silent. When NOT to use: do not treat this reflected attribute as a native defaultChecked; reset uses the baseline captured at form association. |
disabled | disabled | boolean | false | Prevents activation, removes the checkbox from keyboard reach, exposes the unavailable state, and excludes it from form data. When NOT to use: do not use disabled for validation errors or pending state. |
error-text | errorText | string | undefined | – | Message shown in place of the help text once a required checkbox is left unchecked, and its validationMessage. Say what checking it means ("Accept the terms to continue"). Without it the browser's own message shows, in the browser's language. An error set with setCustomValidity outranks it. When NOT to use: do not use it for server-side or cross-field errors; call setCustomValidity for those. |
help-text | helpText | string | undefined | – | One line of help under the checkbox, read with it as its description: what checking it means or commits to. When NOT to use: do not repeat the label, and do not use it for error messages; use error-text. |
indeterminate | indeterminate | boolean | false | Presentation-only mixed state. It renders the dash mark, is forwarded to the internal native input for mixed assistive-technology exposure, and never changes the submitted value. Any user toggle clears it and removes the reflected attribute. When NOT to use: do not submit or persist indeterminate as a third value; model data remains binary through checked. |
label-hint | labelHint | string | undefined | – | Short text shown after the slotted label and read with it as part of the checkbox name, so people know before submitting whether they must check it: "(required)" on a consent the form cannot do without, "(optional)" on one it can, in the page's own language. It changes no validation; set required for that, and keep the two consistent. When NOT to use: do not put what checking it commits to in it (use help-text), errors (use error-text), or a repeat of the label. |
name | name | string | undefined | – | Form-data key contributed when the checkbox is checked. When NOT to use: omit when the checkbox should not submit a value. |
required | required | boolean | false | Requires the checkbox to be checked before form submission can proceed. The invalid appearance appears after a blocked submission attempt or an invalidating user toggle, never on initial render. When NOT to use: do not use required to express group-level rules; compose those at the form/application layer. |
size | size | "lg" | "md" | "sm" | 'md' | Token-backed size: the box is 18, 20 or 24px in onmars. sm also takes the smaller label (13/20, 8px away); md and lg keep the 15px label. The pointer target never drops under 24px. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the text and controls around it. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare data-ki-density on the region instead, which composes with every size. |
value | value | string | undefined | – | Form-data value paired with name when checked. If omitted, the submitted value is on, matching native checkbox behavior. When NOT to use: do not encode the unchecked state here; unchecked checkboxes contribute no form entry. |
Events
| Event | Detail type | Description |
|---|---|---|
change | Event | Fired once after a user toggle (pointer, slotted label or Space) commits, composed across the shadow boundary; checked is already current when listeners run. When to use: react to the committed selection. When NOT to use: do not expect it for programmatic checked writes, which are silent. |
Slots
| Slot | Description |
|---|---|
| (default) | Visible label content. This is the accessible name source and a native activation surface. |
CSS parts
| Part | Description |
|---|---|
control | Visual checkbox box, border, focus ring and currentColor marks. |
error | Error line shown in place of the help text while the checkbox is invalid after the person toggled it or submitted; a polite live region, starting with a decorative error symbol. |
help | Help line under the checkbox, read as its description. |
label | Label wrapper around the default slot. |
label-hint | The label-hint text after the slotted label, inside the label wrapper and part of the accessible name; rendered only while a hint is set. |
CSS custom properties
The public styling contract of ki-checkbox: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-checkbox-border-width | dimension used by the checkbox component for border width. |
--ki-checkbox-checked-active-bg | color used by the checkbox component for checked active background. |
--ki-checkbox-checked-active-border | color used by the checkbox component for checked active border. |
--ki-checkbox-checked-active-fg | color used by the checkbox component for checked active foreground. |
--ki-checkbox-checked-disabled-bg | color used by the checkbox component for checked disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). |
--ki-checkbox-checked-disabled-border | color used by the checkbox component for checked disabled border. |
--ki-checkbox-checked-disabled-fg | color used by the checkbox component for checked disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). |
--ki-checkbox-checked-hover-bg | color used by the checkbox component for checked hover background. |
--ki-checkbox-checked-hover-border | color used by the checkbox component for checked hover border. |
--ki-checkbox-checked-hover-fg | color used by the checkbox component for checked hover foreground. |
--ki-checkbox-checked-rest-bg | color used by the checkbox component for checked rest background. |
--ki-checkbox-checked-rest-border | color used by the checkbox component for checked rest border. |
--ki-checkbox-checked-rest-fg | color used by the checkbox component for checked rest foreground. |
--ki-checkbox-control-size | dimension used by the checkbox component for control size. |
--ki-checkbox-focus-ring-color | color used by the checkbox component for focus ring color. |
--ki-checkbox-focus-ring-offset | dimension used by the checkbox component for focus ring offset. |
--ki-checkbox-focus-ring-shadow | shadow used by the checkbox component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator). |
--ki-checkbox-focus-ring-width | dimension used by the checkbox component for focus ring width. |
--ki-checkbox-gap | dimension used by the checkbox component for gap (MarsUI md label pairing: Space/xl 12px for the 20px box). |
--ki-checkbox-indeterminate-active-bg | color used by the checkbox component for indeterminate active background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). |
--ki-checkbox-indeterminate-active-border | color used by the checkbox component for indeterminate active border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). |
--ki-checkbox-indeterminate-active-fg | color used by the checkbox component for indeterminate active dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). |
--ki-checkbox-indeterminate-disabled-bg | color used by the checkbox component for indeterminate disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). |
--ki-checkbox-indeterminate-disabled-border | color used by the checkbox component for indeterminate disabled border. |
--ki-checkbox-indeterminate-disabled-fg | color used by the checkbox component for indeterminate disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). |
--ki-checkbox-indeterminate-hover-bg | color used by the checkbox component for indeterminate hover background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). |
--ki-checkbox-indeterminate-hover-border | color used by the checkbox component for indeterminate hover border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). |
--ki-checkbox-indeterminate-hover-fg | color used by the checkbox component for indeterminate hover dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). |
--ki-checkbox-indeterminate-rest-bg | color used by the checkbox component for indeterminate rest background (MarsUI Surface/primary_low_em_alpha: brand-500 at 20% light / 56% dark; the master defines no indeterminate hover, so every state keeps the tint). |
--ki-checkbox-indeterminate-rest-border | color used by the checkbox component for indeterminate rest border (Figma draws no border on the 20% tint, but the tint alone measures ~1.3:1 against light pages; the opaque brand ring keeps the WCAG 1.4.11 3:1 control boundary — gate-driven declared deviation, same law that pinned ki.outline.control). |
--ki-checkbox-indeterminate-rest-fg | color used by the checkbox component for indeterminate rest dash (Figma binds Text/primary_med_em brand-500, which measures 2.7:1 against the 56% tint in dark; one em step up keeps the 3:1 non-text law in both schemes — gate-driven compliant alternative). |
--ki-checkbox-invalid-bg | color used by the checkbox component for invalid background. |
--ki-checkbox-invalid-border | color used by the checkbox component for invalid border. |
--ki-checkbox-invalid-fg | color used by the checkbox component for invalid foreground. |
--ki-checkbox-label-font-size | dimension used by the checkbox component for label font size (MarsUI md pairing: body_2 15px for the 20px box). |
--ki-checkbox-label-font-weight | font weight used by the checkbox component for label font weight. |
--ki-checkbox-label-hint-fg | color used by the checkbox component for the label hint after the label text (spec 047: the supporting-text role, a declared a11y deviation from the MarsUI Input_label support text Text/low_em, which reads 2.8-3.13:1 on the onmars light surfaces; under more contrast it strengthens with every other supporting text). |
--ki-checkbox-label-hint-gap | dimension used by the checkbox component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px). |
--ki-checkbox-label-line-height | dimension used by the checkbox component for label line height (MarsUI body_2 24px). |
--ki-checkbox-lg-control-size | dimension used by the checkbox component for the lg box (Checkbox 10030:982 lg: 24px in a 28px cell). |
--ki-checkbox-lg-min-target | dimension used by the checkbox component for the lg min target (Checkbox 10030:982 lg cell: 28px). |
--ki-checkbox-min-target | dimension used by the checkbox component for min target. |
--ki-checkbox-radius | dimension used by the checkbox component for radius (MarsUI Radius/radius_sm 6px bound on the box; Figma corner smoothing is an accepted rasterization gap). |
--ki-checkbox-sm-control-size | dimension used by the checkbox component for the sm box (Checkbox 10030:982 sm: 18px in a 20px cell). |
--ki-checkbox-sm-gap | dimension used by the checkbox component for the sm gap between control and label (Checkbox-label 10095:3846 sm binds Space/md, 8px; spec 050 D4). |
--ki-checkbox-sm-label-font-size | dimension used by the checkbox component for the sm label font size (Checkbox-label 10095:3846 sm: UI/para 13/20; spec 050 D4). |
--ki-checkbox-sm-label-line-height | dimension used by the checkbox component for the sm label line height (Checkbox-label 10095:3846 sm: UI/para 13/20). |
--ki-checkbox-sm-min-target | dimension used by the checkbox component for the sm min target: 24px, the WCAG 2.5.8 minimum, above the master's 20px cell. |
--ki-checkbox-unchecked-active-bg | color used by the checkbox component for unchecked active background. |
--ki-checkbox-unchecked-active-border | color used by the checkbox component for unchecked active border. |
--ki-checkbox-unchecked-active-fg | color used by the checkbox component for unchecked active foreground. |
--ki-checkbox-unchecked-disabled-bg | color used by the checkbox component for unchecked disabled background (MarsUI Surface/disabled_med_em Gray/300 light / White-18 dark). |
--ki-checkbox-unchecked-disabled-border | color used by the checkbox component for unchecked disabled border. |
--ki-checkbox-unchecked-disabled-fg | color used by the checkbox component for unchecked disabled mark (MarsUI Text/base_em Gray/400 light / White-32 dark; retires the deprecated ki.text.muted alias). |
--ki-checkbox-unchecked-hover-bg | color used by the checkbox component for unchecked hover background. |
--ki-checkbox-unchecked-hover-border | color used by the checkbox component for unchecked hover border. |
--ki-checkbox-unchecked-hover-fg | color used by the checkbox component for unchecked hover foreground. |
--ki-checkbox-unchecked-rest-bg | color used by the checkbox component for unchecked rest background. |
--ki-checkbox-unchecked-rest-border | color used by the checkbox component for unchecked rest border. |
--ki-checkbox-unchecked-rest-fg | color used by the checkbox component for unchecked rest foreground. |
--ki-density-target-min | The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1). |
--ki-effect-component-primary-default-shadow | MarsUI Component_effect/primary_default: drop 0/1/1/-0.5 plus inner White/12 0/3/3. Pair with --ki-effect-component-backdrop-filter — CSS cannot mix backdrop blur into box-shadow. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-easing-emphasized-out | Expressive exit curve for selected controls. Onmars eases out without overshoot. |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard | Standard interaction transition easing curve. |
--ki-surface-special-dark-s0-light-s2 | semantic color for surface special dark s0 light s2. |
--ki-surface-special-light-s0-dark-s4 | semantic color for surface special light s0 dark s4. |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-high-em | semantic color for text high em. |
--ki-text-supporting | Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |
Accessibility
Section titled “Accessibility”The default slot is the accessible-name source — unlabeled usage is invalid.
For a single mutually exclusive choice use
ki-radio-group; for an immediate
on/off effect use ki-switch. The composed
change event fires at the host exactly like a native checkbox.