Checkbox

Live variants

default

Wrap long lines

✕ Confirm before continuing.

Markup

<j3w1-checkbox id="example-checkbox-default"><div class="checkbox">
  <label class="checkbox-option">
    <span class="checkbox-control">
      <input class="checkbox-input" type="checkbox" name="example-checkbox-default-wrap" aria-describedby="example-checkbox-default-cb-wrap-message">
      <svg class="checkbox-check" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 8.5l3 3 6-6"></path></svg>
      <svg class="checkbox-dash" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M4 8h8"></path></svg>
    </span>
    <span class="checkbox-text">Wrap long lines <span class="checkbox-required" aria-hidden="true">*</span><span class="checkbox-required sr-only"> required</span></span>
  </label>
  <p class="checkbox-message" id="example-checkbox-default-cb-wrap-message">✕ Confirm before continuing.</p>
</div></j3w1-checkbox>

group

Bar modules CPU load Memory Battery

✕ Choose at least one module.

Markup

<j3w1-checkbox id="example-checkbox-group"><fieldset class="checkbox checkbox-group" aria-describedby="example-checkbox-group-cb-modules-message">
  <legend class="checkbox-legend">Bar modules <span class="checkbox-required" aria-hidden="true">*</span><span class="checkbox-required sr-only"> required</span></legend>
  <label class="checkbox-option">
    <span class="checkbox-control">
      <input class="checkbox-input" type="checkbox" name="example-checkbox-group-modules" value="cpu">
      <svg class="checkbox-check" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 8.5l3 3 6-6"></path></svg>
      <svg class="checkbox-dash" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M4 8h8"></path></svg>
    </span>
    <span class="checkbox-text">CPU load</span>
  </label>
  <label class="checkbox-option">
    <span class="checkbox-control">
      <input class="checkbox-input" type="checkbox" name="example-checkbox-group-modules" value="memory">
      <svg class="checkbox-check" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 8.5l3 3 6-6"></path></svg>
      <svg class="checkbox-dash" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M4 8h8"></path></svg>
    </span>
    <span class="checkbox-text">Memory</span>
  </label>
  <label class="checkbox-option">
    <span class="checkbox-control">
      <input class="checkbox-input" type="checkbox" name="example-checkbox-group-modules" value="battery">
      <svg class="checkbox-check" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 8.5l3 3 6-6"></path></svg>
      <svg class="checkbox-dash" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M4 8h8"></path></svg>
    </span>
    <span class="checkbox-text">Battery</span>
  </label>
  <p class="checkbox-message" id="example-checkbox-group-cb-modules-message">✕ Choose at least one module.</p>
</fieldset></j3w1-checkbox>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@4.0.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/checkbox.css';
import '@j3w1/ui/register/checkbox';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@4.0.0 j3w1-ui copy checkbox --out ./vendor/j3w1/checkbox

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.
`value`	`CustomEvent`	Forwards value to the primary native control.
`required`	`CustomEvent`	Forwards required to the primary native control.
`readonly`	`CustomEvent`	Forwards readonly to the primary native control.
`checked`	`CustomEvent`	Forwards checked to the primary native control.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`value`	`string`	Primary native value; assignment does not fabricate user events.
`checked`	`boolean`	Native checkbox state.
`required`	`boolean`	Native required constraint.
`readOnly`	`boolean`	Native readonly property.
`form`	`HTMLFormElement \| null`	Owning native form. Read only.
`indeterminate`	`boolean`	Native mixed state; Space changes a mixed checkbox to checked.
`values`	`string[]`	Values of checked native options in this instance.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`checkValidity`	`(): boolean`	Check owned native constraints.
`reportValidity`	`(): boolean`	Report the first invalid owned control.
`clear`	`(): void`	Clear an editable primary input and emit native input/change.

events

Name	Type / signature	Meaning
`j3w1-change`	`CustomEvent`	Native change from an owned control, alongside the original native event.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Specimen density

Specimen profile

Checkbox `checkbox`

Family: Basic forms
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native <input type="checkbox"> with <label>; fieldset and legend for a group — APG pattern
specified
demonstrated
test implemented

The native checkbox drawn as a 16px square that fills with the primary action colour and a ✓ or – glyph; single, or a fieldset group of independent choices.

Report an issue with this component

Open component workbench

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`box.bg`	`color.surface.input`approveduse	`#000000`	Form-control fill.
`box.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`box.bg-hover`	`color.interaction.hover.bg`approveduse	`#1c1010`	D-041 interaction.hover.bg: color.primitive.modern.hover.
`box.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`box.bg-checked`	`color.action.primary.bg`approveduse	`#7d1310`	Primary button fill; D-026 darkened it off color12, which stays fixed as heritage ANSI 12.
`box.bg-checked-hover`	`color.action.primary.hover-bg`observeduse	`#911410`	Primary button hover; pair with action.primary.text (D-033).
`box.glyph`	`color.action.primary.text`approveduse	`#ffa2a7`	Primary action labels: bright rose across rest, hover and pressed states (D-033).
`box.ring-checked`	`color.interaction.focus.ring-container`observeduse	`#ffa2a7`	Focus colour for containers and explicitly mapped filled controls (D-015); component rules determine ring geometry.
`box.border-invalid`	`color.status.danger.border`observeduse	`#e53935`	Danger border, 2px on invalid inputs.
`box.bg-disabled`	`color.interaction.disabled.bg`approveduse	`#0d0707`	D-041 interaction.disabled.bg: color.primitive.modern.panel.
`box.border-disabled`	`color.border.disabled`approveduse	`#482b2b`	D-041 border.disabled: color.primitive.modern.divider.
`box.glyph-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`text.default`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`text.disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`legend.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`legend.required-mark`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`message.text`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Single	Group
`default`	Wrap long lines required ✕ Confirm before continuing.	Bar modules required CPU load Memory Battery ✕ Choose at least one module.
`hover`
`focus-visible`
`checked`
`mixed`
`checked+focus-visible`
`checked+disabled`
`disabled`
`invalid`
`required`

Purpose

An independent yes/no choice, or several under one legend. A setting that takes effect immediately is a switch; one of several exclusive options is a radio group. A parent checkbox over a partly selected set shows the mixed state.

Anatomy

Parts as listed in the anatomy. Because the box is the native input, it keeps native focus, form and keyboard behaviour.

States

State	Visual	Non-colour channel
default	16px box, 1px `color.border.control` on `color.surface.input`; text `color.text.default`	—
hover	box → `color.interaction.hover.bg`; checked box → `color.action.primary.hover-bg`	cursor: pointer; hover-capable pointers only
focus-visible	1px dashed `color.interaction.focus.ring` ring at −2px around the box	the ring
checked	fill `color.action.primary.bg`; ✓ in `color.action.primary.text`; border stays `color.border.control`	✓ glyph; `checked`
mixed	fill `color.action.primary.bg`; – in `color.action.primary.text`	– glyph; `indeterminate` / `aria-checked="mixed"`
checked+focus-visible	the fill plus a `color.interaction.focus.ring-container` ring	glyph and ring
checked+disabled	box `color.interaction.disabled.bg`, 1px `color.border.disabled`; ✓ and text `color.text.disabled`	glyph; `disabled`; cursor: not-allowed
disabled	box `color.interaction.disabled.bg`, 1px `color.border.disabled`; text `color.text.disabled`	`disabled`; cursor: not-allowed
invalid	2px `color.status.danger.border` box border; message with the ✕ glyph	border 1 → 2px; glyph; `aria-invalid`
required	`*` after the text or legend in `color.status.danger.text` plus visually hidden “required”	`required`; the mark

Precedence: disabled > invalid > checked > hover; focus-visible is always drawn.

Keyboard

Native; Enter does nothing. A mixed parent becomes checked on the first Space and unchecked on the second, never mixed again by keyboard.

Accessibility

A group’s legend is read before each option. The mixed state reads as “mixed” natively. A required group marks the legend, not every option, and validates on submit. Text and glyphs meet 4.5:1; box edges and rings 3:1.

Portability

Hosts that draw their own indicator make it square, 16px, with the same fill and glyph colours; a host without a mixed indicator draws the dash itself or records the gap.

Non-examples

Rounded or circular boxes. A tick drawn with a border trick or an icon font. A checked state shown by border colour alone. A box under 16px or a row under 24px. The mixed state as a third value. Saving on change. Disabling by opacity. A div with role="checkbox".

Contrast report

18 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
checkbox default border	default	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
checkbox hover border	hover	ui	`color.border.control` `#c81a1a`	`color.interaction.hover.bg` `#1c1010`	3.20	3	pass
checkbox focus-visible border	focus-visible	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
checkbox focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
checkbox checked text	checked	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	4.5	pass
checkbox mixed text	mixed	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	4.5	pass
checkbox checked+focus-visible text	checked+focus-visible	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	4.5	pass
checkbox checked+focus-visible outline	checked+focus-visible	ui	`color.interaction.focus.ring-container` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	3	pass
checkbox invalid border	invalid	ui	`color.status.danger.border` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
checkbox required border	required	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
option text on the panel surface	—	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
legend on the panel surface	—	text	`color.text.bright` `#ffa2a7`	`color.surface.default` `#0d0707`	10.45	4.5	pass
checked box edge against the panel (the border stays border.control)	checked	ui	`color.border.control` `#c81a1a`	`color.surface.default` `#0d0707`	3.44	3	pass
glyph on the hovered checked fill	hover	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.hover-bg` `#911410`	4.75	4.5	pass
validation message on the panel surface	—	text	`color.status.danger.text` `#f07178`	`color.surface.default` `#0d0707`	6.98	4.5	pass
disabled option text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.surface.default` `#0d0707`	4.48	3	pass
disabled glyph (exempt; house floor 3:1)	checked+disabled	ui	`color.text.disabled` `#a3676b`	`color.interaction.disabled.bg` `#0d0707`	4.48	3	pass
disabled border (exempt)	disabled	ui	`color.border.disabled` `#482b2b`	`color.interaction.disabled.bg` `#0d0707`	1.58	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Moves through every checkbox; each is its own tab stop.
`Space`	Toggles; a mixed box becomes checked.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Live variants

default

group

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Checkbox `checkbox`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

group

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Checkbox checkbox

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Checkbox `checkbox`