Lets users turn a single independent option on or off
Installation
-
Install the package
terminal npm install @hashintel/ds-components -
Import the component
app.tsx import { useState } from "react"; import { Checkbox } from "@hashintel/ds-components"; export const IncludeArchivedOption = () => { const [includeArchived, setIncludeArchived] = useState(false); return ( <Checkbox label="Include archived entities" value={includeArchived} onChange={setIncludeArchived} /> ); };
When to use
- Do: Use Checkbox for one independent yes/no choice that takes effect when the form is saved — “Include archived entities”, “Notify teammates”.
- Do: Use it to record explicit agreement, such as accepting terms before creating a workspace.
- Do: Use
indeterminateon a parent checkbox that summarizes a partially selected list, such as a select-all table header.
When not to use
- Don't: Avoid wiring up several related checkboxes by hand — prefer CheckboxGroup, which manages the array value, group name, and selection limits.
- Don't: Don't use a checkbox for a setting that applies the moment it's flipped — use Toggle.
- Don't: Don't use checkboxes for mutually exclusive options — use RadioGroup, or Select when the list is long.
Examples
Basic
Checkbox is always controlled: value holds the checked boolean and onChange receives the next one (see Installation for the state wiring). The default is md-sized and neutral.
Disabled
A disabled checkbox keeps its checked state visible but can't be changed. Explain the constraint nearby — the box alone doesn't say why it's locked.
Invalid
Set invalid when the choice fails validation, such as required terms left unaccepted. Pair it with visible error text — the red box alone doesn't say what's wrong.
Indeterminate
Use indeterminate on a parent checkbox when only some of its children are selected. It's display-only — value remains true or false.
Tones
tone colors the checked box: neutral (default) for everyday options, brand for primary opt-ins such as onboarding choices, success for confirmation-flavored items like completed steps.
Sizes
md is the default; the label text scales with the box. Match the surrounding text — xxs–sm for dense chrome such as table rows and filter panels, lg for prominent confirmations.
Label placement
labelPlacement puts the label right (default) or left of the box.
Label alignment
labelAlign sets the box against a label that wraps onto several lines: top (default) pins it to the first line, center centers it against the whole label.
In forms
value is the checked boolean, not what the form submits: when checked, the hidden native input submits htmlValue (default "on") under name, and nothing when unchecked. required blocks native submission until checked.
import { useState } from "react";
import { Button, Checkbox } from "@hashintel/ds-components";
export const InviteTeammateForm = () => {
const [notifyByEmail, setNotifyByEmail] = useState(true);
const [dpaAccepted, setDpaAccepted] = useState(false);
return (
<form action="/api/invites" method="post">
<Checkbox
label="Notify the teammate by email"
name="notify"
htmlValue="email"
value={notifyByEmail}
onChange={setNotifyByEmail}
/>
<Checkbox
label="I agree to the data processing agreement"
name="dpa"
required
value={dpaAccepted}
onChange={setDpaAccepted}
/>
<Button type="submit" tone="brand">
Send invite
</Button>
</form>
);
};Behavior
- Checkbox renders as one
<label>wrapping a hidden native checkbox, so clicking anywhere on it toggles. Don't nest it inside another label or interactive element. - Long labels wrap rather than truncate. If you prefer truncation, apply it with a
className. invalidsetsaria-invalidon the input.
Content
- Phrase labels positively: "Notify teammates by email", never "Don't send notifications" — unchecking a negative is a double negative.
- Lead with the outcome of checking, in sentence case with no terminal punctuation: "Include archived entities", "Sync to GitHub".
- Try to keep labels to one line — under roughly 8 words. It's generally better to move caveats and detail into nearby helper text.
Accessibility
Checkbox implements the WAI-ARIA checkbox pattern.
What you must do
- Always provide
label— without it the input has no accessible name. When the visible label lives elsewhere, passhtmlForIdand point that label'shtmlForat it. - Don't signal errors with the red box alone — put the error text next to the checkbox.
- Prefer explaining a constraint over
disabled— a disabled box has reduced contrast and doesn't say why it's locked.
API reference
| Prop | Type | Description |
|---|---|---|
| value | boolean | The input value |
| onChange | (value: boolean) => void | The onChange handler |
| label | ReactNode | An optional label rendered alongside the box |
| labelPlacement | "left" | "right" default: "right" | Which side of the box the label is rendered on |
| labelAlign | "top" | "center" default: "top" | Vertical alignment of the box against the label when it wraps over multiple lines |
| tone | "neutral" | "brand" | "success" default: "neutral" | The tone applied when the checkbox is checked |
| indeterminate | boolean default: false | Whether the box renders the indeterminate ("partially checked") state. |
| htmlValue | string default: "on" | An optional value used for native form submissions |
| name | string | The name of the input |
| onFocus | FocusEventHandler<HTMLInputElement> | The onFocus handler |
| onBlur | FocusEventHandler<HTMLInputElement> | The onBlur handler |
| invalid | boolean | Set to show the input as invalid |
| autoFocus | boolean | "never" | Set to true to make the element focused on mount or 'never' to prevent the item being auto-focused |
| disabled | boolean | Set to show the input as disabled |
| required | boolean | Marks the input as required: sets the native required attribute, so assistive technology announces it and form validation blocks empty submits. Purely functional — the input looks unchanged; pair it with Form.Field's required for the visible mark. |
| size | "xxs" | "xs" | "sm" | "md" | "lg" default: "md" | The size (height) of the element |
Was this page helpful?