Skip to content
Kimenpre-v1documentation home
Color scheme

ki-switch

A token-styled switch for binary settings whose change takes effect immediately — always with a slotted label.

Theme for this example
Color scheme for this example
Email notifications
<ki-switch checked>Email notifications</ki-switch>
Theme for this example
Color scheme for this example
Off On Disabled
<ki-switch>Off</ki-switch>
<ki-switch checked>On</ki-switch>
<ki-switch disabled>Disabled</ki-switch>

The composed change event fires at the host; read checked from the target:

import type { KiSwitch } from '@kimen/elements/ki-switch';
const kiSwitch = document.querySelector('ki-switch');
kiSwitch?.addEventListener('change', (event) => {
console.log((event.target as KiSwitch).checked);
});

When to use: binary settings whose change takes effect immediately, always with a slotted label.

When not to use: selections collected for later form submission; use ki-checkbox for recorded choices, ki-radio-group for mutually exclusive choices, and ki-button for actions.

Properties & attributes

AttributePropertyTypeDefaultDescription
checkedcheckedbooleanfalseLive on/off state. Boolean presence semantics apply: any present checked attribute value, including checked="false" or malformed agent output, means on. Omit the attribute to express off. When to use: set the initial on state for a setting that applies immediately. When NOT to use: do not use a switch for choices saved only on submit; use ki-checkbox for that pattern.
disableddisabledbooleanfalsePrevents toggling, removes the switch from keyboard reach, excludes it from form data, and exposes the unavailable state to assistive technology. When to use: make a setting temporarily unavailable while preserving its current state. When NOT to use: do not use disabled for pending or loading states.
help-texthelpTextstring | undefined–One line of help under the switch, read with it as its description: what turning it on changes. When NOT to use: do not repeat the label. A switch has no constraint of its own, so it takes no error text; an error the application sets with setCustomValidity shows in this line's place.
namenamestring | undefined–Form-data key contributed while the switch is on. When to use: include the immediate setting in native form data when on. When NOT to use: omit when no form entry should be submitted.
sizesize"lg" | "md" | "sm" | "xl"'md'Token-backed size: the track is 32 x 18, 40 x 22, 48 x 26 or 56 x 32px in onmars (xl is the design's mobile size), with its thumb. sm also takes the smaller label (13/20, 8px away). 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.
valuevaluestring | undefined–Form-data value submitted while on. Omit for native checkbox parity: the submitted value defaults to on. When to use: submit a domain-specific value instead of the default on. When NOT to use: do not set a value to represent off; off contributes nothing.

Events

EventDetail typeDescription
changeEventFired once after a user toggle commits, composed across the shadow boundary; checked is already current when listeners run. When to use: apply the on/off effect. When NOT to use: do not expect it for programmatic checked writes, which are silent.

Slots

SlotDescription
(default)Label content. This is the accessible name source.

CSS parts

PartDescription
errorLine that shows, in place of the help text, an error the application set with setCustomValidity once the form is submitted; a polite live region, starting with a decorative error symbol.
helpHelp line under the switch, read as its description.
labelLabel wrapper around the default slot.
thumbTraveling handle.
trackOn/off channel.

CSS custom properties

The public styling contract of ki-switch: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-target-minThe 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-small-dark-shadowMarsUI Small_dark_shadow: drop 0/2/3/-1.5 in Elevation/shadow_dark (Black/32 light, Black/48 dark). Lifts small light glyphs off saturated fills — the radio selected dot and the switch pointer carry it in the masters.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-motion-easing-standardStandard interaction transition easing curve.
--ki-switch-border-widthdimension used by the switch component for border width (MarsUI tracks are borderless; the 1px hairline in ki.outline.control is the declared WCAG 1.4.11 deviation at half the former weight, so the control stops reading as an outlined pill).
--ki-switch-checked-active-bordercolor used by the switch component for checked active border.
--ki-switch-checked-active-thumbcolor used by the switch component for checked active thumb.
--ki-switch-checked-active-trackcolor used by the switch component for checked active track.
--ki-switch-checked-disabled-bordercolor used by the switch component for checked disabled border.
--ki-switch-checked-disabled-thumbcolor used by the switch component for checked disabled thumb (MarsUI pointer keeps its light construction in every state including disabled).
--ki-switch-checked-disabled-trackcolor used by the switch component for checked disabled track (MarsUI disabled track keeps the OFF rest fill surface/disabled_med_em; the disabled signal lives in the glyph in the master).
--ki-switch-checked-hover-bordercolor used by the switch component for checked hover border.
--ki-switch-checked-hover-thumbcolor used by the switch component for checked hover thumb.
--ki-switch-checked-hover-trackcolor used by the switch component for checked hover track.
--ki-switch-checked-rest-bordercolor used by the switch component for checked rest border.
--ki-switch-checked-rest-thumbcolor used by the switch component for checked rest thumb.
--ki-switch-checked-rest-trackcolor used by the switch component for checked rest track.
--ki-switch-control-heightdimension used by the switch component for the control footprint height (Toggle md: Space/9xl 28px). The well pads the track by half of (control-height - track-height) on every side.
--ki-switch-control-widthdimension used by the switch component for the control footprint width (Toggle md 10023:1368: Space/14xl 48px). The well is centred in it; set it to the track width, with control-height, to drop the well.
--ki-switch-focus-ring-colorcolor used by the switch component for focus ring color.
--ki-switch-focus-ring-offsetdimension used by the switch component for focus ring offset.
--ki-switch-focus-ring-shadowshadow used by the switch 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-switch-focus-ring-widthdimension used by the switch component for focus ring width.
--ki-switch-gapdimension used by the switch component for gap between the control and its label (Toggle-label md 10101:3996: Space/xl 12px, as checkbox and radio).
--ki-switch-glyph-checkedColor of the enabled checked switch's thumb check. Use transparent to hide it. When visible, maintain 3:1 contrast with the thumb.
--ki-switch-glyph-dash-heightdimension used by the switch component for the disabled dash glyph block size (Figma pointer exports: 8x2 rounded dash).
--ki-switch-glyph-disabledColor of the thumb check or dash on a disabled switch. Use transparent to hide both disabled glyphs.
--ki-switch-glyph-heightdimension used by the switch component for the thumb state glyph block size (Figma pointer exports: 4px check ink height).
--ki-switch-glyph-uncheckedColor of the enabled unchecked switch's thumb dash. Transparent hides it by default. When visible, maintain 3:1 contrast with the thumb.
--ki-switch-glyph-widthdimension used by the switch component for the thumb state glyph inline size (Figma pointer exports: 8px check/dash ink box inside the thumb).
--ki-switch-lg-control-heightdimension used by the switch component for lg control height (Toggle 10023:1125 lg cell: 32px).
--ki-switch-lg-control-widthdimension used by the switch component for lg control width (Toggle 10023:1125 lg cell: 56px).
--ki-switch-lg-min-targetdimension used by the switch component for lg min target (Toggle 10023:1125 lg cell height: 32px).
--ki-switch-lg-thumb-insetdimension used by the switch component for lg thumb inset (Toggle 10023:1125 lg binds Space/xxs, 2px).
--ki-switch-lg-thumb-radiusdimension used by the switch component for lg thumb radius (Toggle 10023:1125 lg pointer binds Radius/small-component/xs).
--ki-switch-lg-thumb-sizedimension used by the switch component for lg thumb height (Toggle 10023:1125 lg pointer: 20px).
--ki-switch-lg-thumb-widthdimension used by the switch component for lg thumb width (Toggle 10023:1125 lg pointer: 26px).
--ki-switch-lg-track-heightdimension used by the switch component for lg track height (Toggle 10023:1125 lg: 26px).
--ki-switch-lg-track-radiusdimension used by the switch component for lg track radius (Toggle 10023:1125 lg binds Radius/small-component/sm).
--ki-switch-lg-track-widthdimension used by the switch component for lg track width (Toggle 10023:1125 lg: 48px).
--ki-switch-lg-well-radiusdimension used by the switch component for lg well radius (Toggle 10023:1125 lg Base binds Radius/small-component/md).
--ki-switch-min-targetdimension used by the switch component for min target (MarsUI component frame is 28px tall for sm/md — the designed interactive footprint).
--ki-switch-sm-control-heightdimension used by the switch component for sm control height (Toggle 10023:1125 sm cell: 28px).
--ki-switch-sm-control-widthdimension used by the switch component for sm control width (Toggle 10023:1125 sm cell: 40px).
--ki-switch-sm-gapdimension used by the switch component for the sm gap between control and label (Toggle_label 10101:3995 sm binds Space/md, 8px; spec 050 D4).
--ki-switch-sm-label-font-sizedimension used by the switch component for the sm label font size (Toggle_label 10101:3995 sm: UI/para 13/20; spec 050 D4).
--ki-switch-sm-label-line-heightdimension used by the switch component for the sm label line height (Toggle_label 10101:3995 sm: UI/para 13/20).
--ki-switch-sm-min-targetdimension used by the switch component for sm min target (Toggle 10023:1125 sm cell height: 28px).
--ki-switch-sm-thumb-insetdimension used by the switch component for sm thumb inset (Toggle 10023:1125 sm binds Space/xxs, 2px).
--ki-switch-sm-thumb-radiusdimension used by the switch component for sm thumb radius (Toggle 10023:1125 sm pointer binds Radius/small-component/xxs).
--ki-switch-sm-thumb-sizedimension used by the switch component for sm thumb height (Toggle 10023:1125 sm pointer: 14px).
--ki-switch-sm-thumb-widthdimension used by the switch component for sm thumb width (Toggle 10023:1125 sm pointer: 18px).
--ki-switch-sm-track-heightdimension used by the switch component for sm track height (Toggle 10023:1125 sm: 18px).
--ki-switch-sm-track-radiusdimension used by the switch component for sm track radius (Toggle 10023:1125 sm binds Radius/small-component/xs).
--ki-switch-sm-track-widthdimension used by the switch component for sm track width (Toggle 10023:1125 sm: 32px).
--ki-switch-sm-well-radiusdimension used by the switch component for sm well radius (Toggle 10023:1125 sm Base binds Radius/small-component/md).
--ki-switch-thumb-insetdimension used by the switch component for thumb inset.
--ki-switch-thumb-radiusdimension used by the switch component for thumb radius (Toggle md Pointer 10023:1371: 22x18 with Radius/small-component/xs).
--ki-switch-thumb-sizedimension used by the switch component for thumb size.
--ki-switch-thumb-widthdimension used by the switch component for thumb inline size (MarsUI md pointer is 22x18 — wider than tall; thumb-size remains the block size).
--ki-switch-track-heightdimension used by the switch component for track height.
--ki-switch-track-radiusdimension used by the switch component for track radius.
--ki-switch-track-widthdimension used by the switch component for track width.
--ki-switch-unchecked-active-bordercolor used by the switch component for unchecked active border.
--ki-switch-unchecked-active-thumbcolor used by the switch component for unchecked active thumb.
--ki-switch-unchecked-active-trackcolor used by the switch component for unchecked active track (one step beyond hover; the master defines no pressed variant).
--ki-switch-unchecked-disabled-bordercolor used by the switch component for unchecked disabled border.
--ki-switch-unchecked-disabled-thumbcolor used by the switch component for unchecked disabled thumb (MarsUI pointer keeps its light construction in every state including disabled).
--ki-switch-unchecked-disabled-trackcolor used by the switch component for unchecked disabled track (MarsUI disabled track keeps the OFF rest fill surface/disabled_med_em; the disabled signal lives in the glyph in the master).
--ki-switch-unchecked-hover-bordercolor used by the switch component for unchecked hover border.
--ki-switch-unchecked-hover-thumbcolor used by the switch component for unchecked hover thumb.
--ki-switch-unchecked-hover-trackcolor used by the switch component for unchecked hover track (Kimen-invented one-step ramp over the corrected rest fill; the master defines no hover variant).
--ki-switch-unchecked-rest-bordercolor used by the switch component for unchecked rest border.
--ki-switch-unchecked-rest-thumbcolor used by the switch component for unchecked rest thumb.
--ki-switch-unchecked-rest-trackcolor used by the switch component for unchecked rest track (MarsUI OFF track = surface/disabled_med_em #dddfe4 light / White-18 dark — a solid soft fill, not an outlined pill).
--ki-switch-well-bg-endcolor used by the switch component for the bottom of the well gradient (Toggle md Base).
--ki-switch-well-bg-startcolor used by the switch component for the top of the well gradient (Toggle md Base: Surface/s3 to Surface/s1). Transparent drops the well.
--ki-switch-well-radiusdimension used by the switch component for the radius of the well that holds the track (Toggle md Base: Radius/small-component/md).
--ki-switch-xl-control-heightdimension used by the switch component for xl control height (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) cell: 40px).
--ki-switch-xl-control-widthdimension used by the switch component for xl control width (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) cell: 64px).
--ki-switch-xl-min-targetdimension used by the switch component for xl min target (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) cell height: 40px).
--ki-switch-xl-thumb-insetdimension used by the switch component for xl thumb inset (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) binds Space/xs, 4px).
--ki-switch-xl-thumb-radiusdimension used by the switch component for xl thumb radius (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) pointer binds Radius/small-component/xs).
--ki-switch-xl-thumb-sizedimension used by the switch component for xl thumb height (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) pointer: 24px).
--ki-switch-xl-thumb-widthdimension used by the switch component for xl thumb width (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) pointer: 32px).
--ki-switch-xl-track-heightdimension used by the switch component for xl track height (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6): 32px).
--ki-switch-xl-track-radiusdimension used by the switch component for xl track radius (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) binds Radius/small-component/md).
--ki-switch-xl-track-widthdimension used by the switch component for xl track width (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6): 56px).
--ki-switch-xl-well-radiusdimension used by the switch component for xl well radius (Toggle 10023:1125 mobile, shipped as xl (spec 050 D6) Base binds Radius/small-component/lg).
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text high em.
--ki-text-supportingSupporting 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-bodysemantic font family for typography family body.
--ki-typography-line-height-body-2semantic dimension for typography line height body 2.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

The default slot is the accessible-name source — unlabeled usage is invalid. The thumb travel follows the writing direction in RTL, and the transition is gated behind prefers-reduced-motion. For selections collected for later form submission use ki-checkbox; for mutually exclusive choices use ki-radio-group.

Open ki-switch in Storybook