Checkbox
Make an independent choice with native form behavior and a tri-state presentation.
Try it
<hui-checkbox id="playground-checkbox" name="updates" value="yes">
<span>Email me about product updates</span>
</hui-checkbox>- data-state
- Waiting for enhancement
No component events yet.
Usage
Use hui-checkbox for an independent boolean choice, including a tri-state indeterminate presentation. It renders a native <input type="checkbox"> so form behavior, keyboard interaction, and browser semantics remain available.
Do not use it for mutually exclusive choices (use a radio group), an immediate on/off setting (use a switch), or a command/action (use a button).
The library ships a minimal base control style in components.css for the native checkbox, focus ring, and checked or indeterminate affordances. Consumers can override it and should use the Layer 2 aliases from src/styles/tokens.css.
Anatomy
- Host:
hui-checkbox - Label part:
[data-part="label"] - Native control:
input[type="checkbox"] - Label content: default slot
- State mirror: host
data-state="checked|unchecked|indeterminate"
Examples
<section aria-labelledby="basic-h">
<h2 id="basic-h">Basic</h2>
<hui-checkbox name="notify" value="yes">
<b>Email</b> me about updates
</hui-checkbox>
<hui-checkbox name="tos" value="accepted" checked>
I accept the terms
</hui-checkbox>
<hui-checkbox name="waitlist" value="join" indeterminate>
Join waitlist
</hui-checkbox>
<hui-checkbox name="locked" value="admin" disabled>
Admin access
</hui-checkbox>
</section>
<section aria-labelledby="group-h">
<h2 id="group-h">Group</h2>
<hui-checkbox-group id="toppings" aria-label="Toppings" name="toppings">
<hui-checkbox name="toppings" value="avocado" checked>Avocado</hui-checkbox>
<hui-checkbox name="toppings" value="bacon">Bacon</hui-checkbox>
<hui-checkbox name="toppings" value="tomato">Tomato</hui-checkbox>
</hui-checkbox-group>
</section>API reference
| Attribute/property | Meaning |
|---|---|
checked | Committed boolean value; reflected by the write path. |
indeterminate | Presents the tri-state indeterminate state. |
disabled | Disables the native input. |
name | Native form field name. |
value | Native submitted value. |
Events:
hui-checked-change: committed checked value changed.hui-state-change: derived state changed, including indeterminate changes.
States and styling
| State | Contract and styling guidance |
|---|---|
| Default / unchecked | data-state="unchecked"; use text, border, and background aliases. |
| Hover | Native pointer state; use --hui-color-interactive-hover without changing semantics. |
| Active | Pressed pointer state; use --hui-color-interactive-active. |
| Focus | Preserve the native focus behavior or provide a visible ring with --hui-color-focus-ring and --hui-size-focus-ring. |
| Checked | data-state="checked"; use --hui-color-interactive for the selected indicator. |
| Indeterminate | data-state="indeterminate"; the fixture uses --hui-color-danger. |
| Disabled | Native disabled; use --hui-color-interactive-disabled and --hui-color-disabled-background. |
| Error | No separate error attribute is implemented. Consumers may use aria-invalid="true" and pair it with an associated text error; use --hui-color-danger and do not rely on color alone. |
Attributes are the source of truth. Style derived state with data-state, ARIA attributes, and the --hui-* token aliases.
Accessibility and keyboard support
The native checkbox remains the accessible control. Use Space to toggle it, keep its visible label, and do not rely on color alone for its state.
SSR and forms
Checkbox preserves source-of-truth attributes and accessible state in server-rendered light-DOM markup. Use stable IDs when the component generates relationships; client enhancement adds interaction without changing the public contract.
Code
<link rel="stylesheet" href="./styles/tokens.css" />
<link rel="stylesheet" href="./styles/a11y.css" />
<link rel="stylesheet" href="./styles/components.css" />
<hui-checkbox name="updates" value="yes"> Email me about updates </hui-checkbox>
<hui-checkbox name="terms" value="accepted" checked>
I accept the terms
</hui-checkbox>
<hui-checkbox id="playground-checkbox" name="updates" value="yes">
<span>Email me about product updates</span>
</hui-checkbox>