Checkbox

Basic Usage

Click the box or its label to toggle the state. The checked state follows the selected visual variant with either fill or tick motion.

Checkbox

Variants

The default checkmark variant shows the inner tick. Use variant="fill" when you want a quieter pure filled square.

Checkbox variants

Label First

Use label-placement="start" to render the visible label before the checkbox box.

Checkbox (label start)

No Label

When there is no label or default slot, pass aria-label so assistive technology can identify the control.

Checkbox (no label)

Disabled State

disabled removes focusability and prevents click or keyboard toggles while preserving the current checked state.

Checkbox (disabled)

Loading State

Use loading when the checked state needs server confirmation: the box becomes a spinning ring, the tick, dash, and fill all stand down, and the ring's color carries the state instead — neutral grey when unchecked, primary when checked or mixed. Pointer and keyboard toggles are blocked.

Checkbox (loading)

Using Slots

The default slot replaces label as the visible label. Use it for rich text, helper copy, icons, or emphasis.

Checkbox (slot)

API

Props

Events

Slots

Best Practices

• Prefer a visible label or default slot. Use ariaLabel only for icon-only or visually label-less controls.
• Keep disabled as the single source for inert state; disabled checkboxes are removed from tab order and emit neither update:modelValue nor change.
• loading and disabled say different things: "committing" versus "unavailable". Using disabled for a busy control makes it look permanently inert.
• Do not write modelValue back optimistically while loading is set. Leave the box on the old value, commit on success, and simply clear loading on failure so the state stays where it was.
• Use labelPlacement="start" for compact settings rows where the text should align before the control.

Review Notes

• Reviewed against packages/tuffex/packages/components/src/checkbox/src/TxCheckbox.vue and checkbox.test.ts.
• Loading contract: loading is a purely visual and blocking state; the component owns no async logic. The ring's color still follows modelValue / indeterminate, so it sits on the old value to show that this toggle has not landed yet.
• Known loading trade-off: checked and mixed look identical while loading (both draw a primary ring); aria-checked="mixed" is what preserves the difference. Keeping the fill and drawing a white ring on it was tried first, but the white ring is close to invisible against a light page, so ring-coloring won.
• Accessibility note: the root element owns role="checkbox", aria-checked, and keyboard handling; provide a visible label or default slot whenever possible, and reserve ariaLabel for controls with no visible text.
• Motion fallback: The ring stops rotating under prefers-reduced-motion: reduce; its gapped border is a static glyph on its own, so the busy cue survives.
• Verified coverage: checkbox.test.ts covers rendered labels, aria-label fallback behavior, label placement, the default checkmark variant plus explicit fill and checkmark variants, click emits, disabled blocking, plus loading blocking, is-loading staying separate from is-disabled, a partial selection still reporting mixed while loading, and the aria-busy lifecycle.

Source

• Component source: packages/tuffex/packages/components/src/checkbox/src/TxCheckbox.vue.
• Export alias: packages/tuffex/packages/components/src/checkbox/index.ts exports both TuffCheckbox and TxCheckbox.
• Coverage: packages/tuffex/packages/components/src/checkbox/__tests__/checkbox.test.ts verifies click toggles, ARIA labelling, slot precedence, variant classes, and disabled blocking; keyboard activation is inherited from the native <button> element.