Inputs
Checkbox
A native checkbox with an adjacent label and description.
Import
import { Checkbox, CheckboxControl } from "@loamui/core";Usage
Every example has a CSStab. That’s the real, complete stylesheet for the component: plain, static CSS, with nothing running in the browser.
Basic usage
Checked
With description
Disabled
Guidance
When to use it
- For a single on/off choice (accept terms, stay signed in).
- For selecting any number of options from a list: group related checkboxes in a Fieldset.
- Inside a Field for full control, compose the bare box so labels never nest: <Field.Label><CheckboxControl /> …</Field.Label>.
When not to
- For one choice among several mutually exclusive options: use Radio.
- For an instant on/off toggle that takes effect immediately: use Switch.
Accessibility
- Renders a real <input type="checkbox"> wrapped by its label, so clicking the text toggles it and the state is announced natively.
- Supports an indeterminate (mixed) visual for a 'select all' parent, set on the DOM node. It is a display state, not a third value.
- When placed inside a Field it reads its id, aria-describedby and aria-invalid from context; standalone it wires its own label and description.
- Errors come from Field composition: wrap the checkbox in a Field.Root and add a Field.Error after the control, which marks it invalid and announces the message.
- Group multiple checkboxes under a Fieldset so the legend names the set in the accessibility tree.
How it works
A native checkbox, styled by accent-color
This is a plain <input type="checkbox">. No custom SVG box. The elements layer paints it with the platform's own accent-color (the neutral primary), so the checked and indeterminate marks, keyboard behaviour and forced-colours support all come from the browser. The component adds only the label/description wiring and the invalid affordance. A context region recolours it because accent-color follows the primary token.
One box or a group
A single checkbox is for one self-contained agreement or opt-in whose label is a complete statement (“Agree to the terms of service”). Several related options belong in a Fieldset whose legend asks the question. Because checkboxes and radios look alike, say in the legend or description that users can select all that apply.
Write the label positively
The label states what happens when the box is ticked, in positive, unambiguous words: “Send me email updates”, never “Don't send me emails”. A negated label makes ticking mean refusing and unticking a double negative, and users acting quickly resolve it wrong.
Leave boxes unticked
A pre-ticked box gets submitted by everyone who never read it, so the data records a choice nobody made, and for consent it records nothing at all. Start unticked, so every tick is a deliberate act.
Error messages
Say what happened and how to fix it, in the words of the question itself. See the writing guidance on the Field page.
| Situation | Message |
|---|---|
| A required agreement is unticked | Select [whatever the checkbox label states] to continue |
| Nothing in a required group is selected | Select [whatever the legend asks for] |
| Too many options are selected | Select no more than [N] [things] |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | ReactNode | — | Label rendered next to the checkbox. |
description | ReactNode | — | Helper text rendered below the label. |
indeterminate | boolean | — | Render the partially-checked (dash) visual state. |
wrapperClassName | string | — | Class for the label-row wrapper element (the input keeps className). |
...others | InputHTMLAttributes | — | All native <input> props (except type and size) are forwarded. |
Parts
CheckboxControl
The bare box without a label, for composing inside a Field where the label lives on Field.Label. It reads its wiring (id, aria-describedby, aria-invalid) from the field context, and takes the same props as Checkbox minus label, description and wrapperClassName.