Checkbox
Checkbox form control. Semetrika's checkbox styles the native <input type="checkbox"> via an element selector so every checkbox in a form is consistent without any extra markup. Native semantics (checked, disabled, indeterminate, focus, label association) are preserved; custom drawing is layered on with appearance: none and a pseudo-element checkmark.
Usage
When to use
- To allow users to select one or more options from a list
- To toggle a single setting on or off
- To confirm acceptance (e.g. terms and conditions) inline with other form fields
When not to use
- For mutually exclusive choices - use radio buttons
- For an on/off control that takes effect immediately - use switch
- For quick filter pills - use chip
Do
- Always pair a checkbox with a
<label>that names the option - Group related checkboxes inside a fieldset with a legend
- Use the indeterminate state only for parent/child hierarchies
Don't
- Don't rely on color alone to show the checked state
- Don't disable a checkbox without explaining why
- Don't use a checkbox for an immediate-action toggle
API
Slots
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text for the checkbox. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | - | Name attribute for the input element. |
value | string | - | Value attribute for the input element. Distinguishes the boxes of a group that share one name. |
id | string | - | HTML id of the input. Used to associate the label. |
is_checked | boolean | - | Renders the checked attribute. |
is_disabled | boolean | - | Renders the disabled attribute. |
is_required | boolean | - | Renders the required attribute. |
is_invalid | boolean | - | Marks the control as invalid. Renders aria-invalid="true" when set. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
Examples
Default
Unchecked, checked, and disabled checkboxes.
Sizes
Sm, default, and lg variants stacked vertically. The checkmark scales proportionally with the box.
Motion
Animation is on by default and is controlled by two chained CSS custom properties: the global --option-animations and the component-scoped --option-checkbox-animations. The transition duration resolves as base × --option-checkbox-animations × --option-animations. Set either factor to 0 (inline on a single instance, scoped on any ancestor, or globally) to disable the checkbox transition. prefers-reduced-motion: reduce already zeroes --option-animations automatically.
Indeterminate
Checkbox in the indeterminate state for parent/child hierarchies.
Invalid
Checkbox communicating a validation error via aria-invalid.
In group
Multiple checkboxes grouped inside a fieldset with a legend.
Required
A required consent box. The label carries no asterisk here, because a single checkbox states its obligation through the control rather than a marker on the text.
Wrapping
The consumer-authored <label><input type="checkbox"> Text</label> form. Semetrika's twig template emits the sibling form (<input> + <label>), but page authors and CMS integrations frequently hand-write the wrapping form for inline consent or filter rows. The wrapping label renders as inline-flex with align-items: center so the glyph and the surrounding text share a true vertical center.
Accessibility
- WCAG 2.2 AA
- Native
<input type="checkbox">semantics preserved - Every checkbox has an associated
<label> - Validation state communicated via
aria-invalid - Visible focus ring on keyboard focus
- Disabled state communicated to assistive tech
- Indeterminate state exposed to assistive tech when used
- Animation respects
prefers-reduced-motionvia the chained--option-animationsand--option-checkbox-animationsmultipliers