--- name: checkbox-usage description: > Use after component-usage-ux when an app needs the low-level @techsio/ui-kit Checkbox atom, including invalid and indeterminate states, while preferring form molecules for labeled form rows. metadata: component_version: "1.3.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/atoms/checkbox.tsx libs/ui/src/molecules/form-checkbox.tsx libs/ui/src/tokens/components/atoms/_checkbox.css libs/ui/stories/atoms/checkbox.stories.tsx libs/ui/src/atoms/checkbox.figma.ts" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit Checkbox Usage Use `Checkbox` for the bare control. Use `FormCheckbox` when the UI includes a label, helper text, validation text, or a form-field layout. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `Checkbox`. **Use it when** - Bare selection controls inside tables and lists (row selection, select all). - Custom compositions where the label/help structure is provided by the surrounding component. **Use something else when** | Need | Use instead | | --- | --- | | A checkbox with its own label, help or error | FormCheckbox | | A setting that applies immediately | Switch | | One exclusive option | RadioGroup | **Do** - Give bare checkboxes an accessible name (`Select Linen shirt`, `Select all products on this page`). - Use the indeterminate state for a partially selected group. - Make the whole row or label clickable where the pattern allows. **Don't** - Use a checkbox to trigger an immediate action (that is a Switch or Button). - Reverse meaning with negative labels (`Don't send emails`). **Copy and states** - Positive, parallel statements; no trailing punctuation for short labels. **Behaviour (from the UX spec)** - Checking a row only selects it; export, assign or delete is a separate named action. A select-all on a paged list selects the visible page — say so. - `indeterminate` is a partial group, never a third answer; in the mixed state, activation selects the whole group. **Figma → code** | Figma | Code | | --- | --- | | `state=checked` / `indeterminate` | `checked` / `indeterminate` | | `state=error` | `invalid` (combinable with `checked` in code) | | `disabled=true` | `disabled` | | — (not in Figma) | `size="sm" \| "md" \| "lg"`, `readOnly` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Checkbox → UX guidelines*. ## Setup ```tsx import { Checkbox } from "@techsio/ui-kit/atoms/checkbox" ``` Supported component-specific props: ```text indeterminate: boolean invalid: boolean ``` The component also accepts native checkbox input attributes. ## Core Patterns ### Canonical sizing `size="sm" | "md" | "lg"` uses the same box dimensions as FormCheckbox, with `md` as the default. The default is now 24px rather than the legacy 16px atom; use `sm` explicitly for dense table/list selection (18px). Numeric native `size` is not supported. Both checkmarks and mixed dashes scale with the box. ### Native read-only behavior `readOnly` preserves the native checkbox focus target and submitted value while blocking pointer and Space toggles. It exposes `aria-readonly` and a neutral, full-contrast value surface. Disabled takes precedence. Use FormCheckbox for automatically associated inline help and validation. ### Border width tokens `--border-width-checkbox` controls the normal border, including checked, indeterminate, and disabled states. Invalid checkboxes continue to use `--border-width-validation` instead. Override the existing tokens in the consumer's scope; do not add descendant border rules. ### Prefer FormCheckbox for labeled rows ```tsx import { FormCheckbox } from "@techsio/ui-kit/molecules/form-checkbox" ``` Do not manually recreate label/help/error layout when the molecule exists. ### Use indeterminate for partial selection ```tsx ``` `indeterminate` is wired to the DOM property in `checkbox.tsx`. ### Use invalid for visual and ARIA state ```tsx ``` `invalid` maps to `aria-invalid` and `data-invalid`. Associate a visible error with `aria-describedby`; a red border alone does not explain the problem. ### Controlled and uncontrolled selection Use `checked` plus `onChange` for controlled selection, or `defaultChecked` for an uncontrolled initial value. Do not supply both. For select-all, compute `checked={allSelected}` and `indeterminate={someSelected && !allSelected}`; Space or click selects the whole partially selected group. Disabled mixed controls use the same disabled surface and icon treatment as disabled checked controls. Mixed selection is a horizontal dash, not a dot or checkmark, even when the native checked value is also true. The visual mixed state does not change the native checked value or form submission semantics. Corners remain squarish even when a theme's general small radius would make a small control circular; override `--radius-checkbox-control` for an intentional scoped shape. Explain why unavailable controls cannot be changed. ## Common Mistakes ### HIGH Native checkbox Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/atoms/checkbox.tsx ### HIGH Manual form row Wrong: ```tsx ``` Correct: ```tsx ``` Source: libs/ui/src/molecules/form-checkbox.tsx ### HIGH Inline state colors Wrong: ```tsx ``` Correct: ```tsx ``` Use `_checkbox.css` or app token overrides for visual changes. Source: libs/ui/src/tokens/components/atoms/_checkbox.css ### MEDIUM Missing accessible label Wrong: ```tsx ``` Correct: ```tsx ``` or use `FormCheckbox` with a visible label. ## State consistency Read-only controls do not invoke `onChange` or mutation click handlers. Controlled application state stays unchanged after both pointer/Space activation and unrelated parent rerenders; parents may still intentionally replace the controlled value. ## Validation Commands ```sh rg -n "]*type=\"checkbox\"" apps rg -n "]*className=.*(accent-|bg-|border-|text-)" apps rg -U -n "]*>\\s*" apps rg -P -n "]*(aria-label|aria-labelledby|id=))" apps ``` ## Silent native form reset Native reset calls no value-change callbacks and dispatches no native `input` or `change` events, in controlled or uncontrolled usage. Uncontrolled controls silently restore their default; controlled controls keep the latest parent value and re-sync visible/accessibility/native submission state to it. Handle the form's `onReset` to intentionally change parent state. Canceled resets leave every channel unchanged. Reset does not synthesize events or move focus; the first real user edit afterward emits exactly one normal callback, including when the same value was entered before reset.