Skip to main content
Skip to Content

Lets users turn a single independent option on or off

Installation

  1. Install the package

    terminal
    npm install @hashintel/ds-components
  2. 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 indeterminate on 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.

app.tsx
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.
  • invalid sets aria-invalid on 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, pass htmlForId and point that label's htmlFor at 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

PropTypeDescription
value
boolean
onChange
(value: boolean) => void
label
ReactNode
labelPlacement
"left" |⁠ "right"
default: "right"
labelAlign
"top" |⁠ "center"
default: "top"
tone
"neutral" |⁠ "brand" |⁠ "success"
default: "neutral"
indeterminate
boolean
default: false
htmlValue
string
default: "on"
name
string
onFocus
FocusEventHandler<HTMLInputElement>
onBlur
FocusEventHandler<HTMLInputElement>
invalid
boolean
autoFocus
boolean |⁠ "never"
disabled
boolean
required
boolean
size
"xxs" |⁠ "xs" |⁠ "sm" |⁠ "md" |⁠ "lg"
default: "md"

Was this page helpful?

On this page