Skip to main content

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​

SlotRequiredDescription
labelYesVisible label text for the checkbox.

Props​

PropTypeDefaultDescription
namestring-Name attribute for the input element.
valuestring-Value attribute for the input element. Distinguishes the boxes of a group that share one name.
idstring-HTML id of the input. Used to associate the label.
is_checkedboolean-Renders the checked attribute.
is_disabledboolean-Renders the disabled attribute.
is_requiredboolean-Renders the required attribute.
is_invalidboolean-Marks the control as invalid. Renders aria-invalid="true" when set.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-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-motion via the chained --option-animations and --option-checkbox-animations multipliers
  • fieldset - semantic grouping of related controls
  • radio - mutually exclusive choices
  • switch - immediate-action on/off control