Checkbox
Use Checkbox component to turn an option on or off.
Import
JSX
import Checkbox from '@box-kite/react/components/checkbox';Basic Checkbox
JSX
<Checkbox label="Accept the terms" name="terms" defaultChecked />The label is the component's job
label renders the text inside a <label> that wraps the input. The association is implicit, so there is no htmlFor/id pair to generate or keep in sync, and the whole row is a click target — which is what a checkbox row is expected to be. A checkbox with no label is the most common accessibility failure there is, so this is not left to the consumer.Style that
<label> with labelProps; every other Box prop still styles the box itself. Leave label out and nothing wraps the input at all — the markup is exactly what it was before.JSX
<Checkbox label="Accept the terms" name="terms" labelProps={{ gap: 3, fontSize: 14 }} />Indeterminate
JSX
<Checkbox label="Select all rows" name="rows" indeterminate />The mixed state is announced, not just drawn
indeterminate is a DOM property, not an attribute — set it and the browser draws the dash, but the accessibility tree still says checked or not checked. The component adds aria-checked="mixed" alongside it, which is what a screen reader reads out. A parent checkbox over a partly-selected list is the case this exists for.indeterminate is a pseudo-class style prop as well as a state, so the tuple form carries both: indeterminate={[mixed, { opacity: 0.6 }]} is the state first and what :indeterminate should look like second.Disabled Checkbox
JSX
<Checkbox label="Accept the terms" disabled defaultChecked />Clean Checkbox
JSX
<Checkbox clean defaultChecked />On or off, rather than checked?
A setting that takes effect immediately is a switch, not a checkbox.
Switch is the same input underneath with role="switch" and a track-and-thumb style — see its page.Checkbox props
Everything below is this component’s own. All 235 of Box’s style props work on it too, and those are on /box rather than repeated here.
| Prop | Type | Default | What it does |
|---|---|---|---|
name | string | — | What the checkbox submits under. Needed for a form; a controlled checkbox can do without one. |
props | CheckboxTagProps | — | Attributes for the <input> itself — type is the component's, and so is aria-checked. |
onInput | (e: React.ChangeEvent<HTMLInputElement>) => void | — | Fires on every click or keystroke. On a checkbox this is the same moment as onChange. |
onChange | (e: React.ChangeEvent<HTMLInputElement>) => void | — | Fires when the box is ticked or cleared. e.target.checked is the new state. |
value | string | number | — | The value the form submits when it is checked. Defaults to "on", as HTML does. |
autoFocus | boolean | — | Focus it on mount. One per page at most — a stolen focus is a lost place in the document. |
readOnly | boolean | — | Rendered and read, but not toggleable. Unlike disabled it stays in the tab order and submits. |
defaultChecked | boolean | — | The state it starts in when the checkbox is uncontrolled. Pass checked instead to control it. |
label | React.ReactNode | — | The text beside the checkbox — rendered inside a <label> that wraps the input, so the association is the component's job. Without it a consumer has to wire htmlFor/id by hand, and a checkbox with no label is the single most common accessibility failure there is. |
labelProps | BoxProps<'label'> | — | Styles for the wrapping <label>: the row's layout, not the box's own appearance. |
Checkbox keyboard
| Key | Result |
|---|---|
Tab | Focuses the checkbox. It is one tab stop, whether or not it carries a label. |
Space | Ticks and clears it. The platform supplies this one. |
Checkbox accessibility
Implements the WAI-ARIA APG pattern.
- A real
<input type="checkbox">, so focus, the checked state, the disabled state and form submission are the platform's rather than this component's. labelrenders the<label>wrapping the input, which is what names it — without one a checkbox is the commonest accessibility failure there is.indeterminatesets the DOM property *and*aria-checked="mixed": the browser draws from the first, a screen reader reads the second, and a checkbox with only the property is read as unchecked.
Swept with axe on every release, in 2 states:
Checkbox, Checkbox (indeterminate). No violations, with contrast and landmark rules left to a human. Screen-reader results are not published yet.Checkbox style tree
Every part the component draws is a node with a name, so a default can be restyled with
Box.components() instead of a selector — and a variant is a name too.checkboxvariants: datagrid