Checkbox

A native checkbox with Harmo's appearance. Pair it with a label in a horizontal Field. For a setting that applies at once, use a Switch.

Installation

bun add @harmo-ui/css @harmo-ui/react

npm install @harmo-ui/css @harmo-ui/react

pnpm add @harmo-ui/css @harmo-ui/react

yarn add @harmo-ui/css @harmo-ui/react

bunx harmo-ui add checkbox

npx harmo-ui add checkbox

pnpm dlx harmo-ui add checkbox

yarn dlx harmo-ui add checkbox

Usage

import { Checkbox, CheckboxGroup, Field } from "@harmo-ui/react";

<CheckboxGroup label="Notify me about" name="notify" defaultValue={["messages", "mentions"]}>
  <Field orientation="horizontal" label="New messages">
    <Checkbox value="messages" />
  </Field>
  <Field orientation="horizontal" label="Mentions">
    <Checkbox value="mentions" />
  </Field>
</CheckboxGroup>

Examples

This site is using your theme

States

Unchecked, checked, and mixed, each in a horizontal Field with its label. Mixed is the indeterminate DOM property, which has no HTML attribute: a script sets it, so it doesn't show in the markup.

Email me updates

Send a weekly summary

Select all reports

<>
  <Field orientation="horizontal" label="Email me updates">
    <Checkbox name="email-updates" />
  </Field>
  <Field orientation="horizontal" label="Send a weekly summary">
    <Checkbox name="weekly-summary" defaultChecked />
  </Field>
  <Field orientation="horizontal" label="Select all reports">
    <Checkbox name="all-reports" indeterminate />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="email-updates" name="email-updates" />
  <label class="hlabel" for="email-updates">Email me updates</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="weekly-summary" name="weekly-summary" checked />
  <label class="hlabel" for="weekly-summary">Send a weekly summary</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="all-reports" name="all-reports" />
  <label class="hlabel" for="all-reports">Select all reports</label>
</div>

Disabled

disabled dims the checkbox in any state, and its label turns gray.

Updates unavailable

Summary enabled by your administrator

Some reports shared by your administrator

<>
  <Field orientation="horizontal" label="Updates unavailable">
    <Checkbox disabled />
  </Field>
  <Field
    orientation="horizontal"
    label="Summary enabled by your administrator"
  >
    <Checkbox defaultChecked disabled />
  </Field>
  <Field
    orientation="horizontal"
    label="Some reports shared by your administrator"
  >
    <Checkbox disabled indeterminate />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="updates-unavailable" disabled />
  <label class="hlabel" for="updates-unavailable">Updates unavailable</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="managed-summary" checked disabled />
  <label class="hlabel" for="managed-summary">Summary enabled by your administrator</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="managed-reports" disabled />
  <label class="hlabel" for="managed-reports">Some reports shared by your administrator</label>
</div>

Custom size

--harmo-checkbox-size resizes the box, and the marks scale with it; here 24px instead of 20px.

Send a weekly summary

Select all reports

<>
  <Field orientation="horizontal" label="Send a weekly summary">
    <Checkbox name="large-summary" style={{ "--harmo-checkbox-size": "24px" } as CSSProperties} defaultChecked />
  </Field>
  <Field orientation="horizontal" label="Select all reports">
    <Checkbox name="large-reports" style={{ "--harmo-checkbox-size": "24px" } as CSSProperties} indeterminate />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input
    class="hcheckbox"
    type="checkbox"
    id="large-summary"
    name="large-summary"
    style="--harmo-checkbox-size: 24px"
    checked
  />
  <label class="hlabel" for="large-summary">Send a weekly summary</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input
    class="hcheckbox"
    type="checkbox"
    id="large-reports"
    name="large-reports"
    style="--harmo-checkbox-size: 24px"
  />
  <label class="hlabel" for="large-reports">Select all reports</label>
</div>

With a description

.hfield-content holds the label and a description, connected to the checkbox with aria-describedby.

Email me about activity across my teams

A weekly summary. You can change this at any time.

<Field
  orientation="horizontal"
  label="Email me about activity across my teams"
  description="A weekly summary. You can change this at any time."
>
  <Checkbox name="activity-updates" />
</Field>

<div class="hfield" data-orientation="horizontal">
  <input
    class="hcheckbox"
    type="checkbox"
    id="activity-updates"
    name="activity-updates"
    aria-describedby="activity-updates-description"
  />
  <div class="hfield-content">
    <label class="hlabel" for="activity-updates">Email me about activity across my teams</label>
    <p class="hdescription" id="activity-updates-description">
      A weekly summary. You can change this at any time.
    </p>
  </div>
</div>

Group

Related checkboxes go in a Field with role="group", named by its label.

Notify me about

New messages

Mentions

Failed campaigns

<CheckboxGroup
  label="Notify me about"
  name="notify"
  defaultValue={["messages", "mentions"]}
>
  <Field orientation="horizontal" label="New messages">
    <Checkbox value="messages" />
  </Field>
  <Field orientation="horizontal" label="Mentions">
    <Checkbox value="mentions" />
  </Field>
  <Field orientation="horizontal" label="Failed campaigns">
    <Checkbox value="failures" />
  </Field>
</CheckboxGroup>

<div class="hfield" role="group" aria-labelledby="notify-label">
  <span class="hlabel" id="notify-label">Notify me about</span>
  <div class="hfield" data-orientation="horizontal">
    <input class="hcheckbox" type="checkbox" id="notify-messages" name="notify" value="messages" checked />
    <label class="hlabel" for="notify-messages">New messages</label>
  </div>
  <div class="hfield" data-orientation="horizontal">
    <input class="hcheckbox" type="checkbox" id="notify-mentions" name="notify" value="mentions" checked />
    <label class="hlabel" for="notify-mentions">Mentions</label>
  </div>
  <div class="hfield" data-orientation="horizontal">
    <input class="hcheckbox" type="checkbox" id="notify-failures" name="notify" value="failures" />
    <label class="hlabel" for="notify-failures">Failed campaigns</label>
  </div>
</div>

Long label

In a narrow container, drawn dashed here, the label wraps and the checkbox stays beside its first line.

Send me detailed updates about changes to reports and activity across every team in my account

<Field
  orientation="horizontal"
  label="Send me detailed updates about changes to reports and activity across every team in my account"
>
  <Checkbox name="detailed-updates" />
</Field>

<div class="hfield" data-orientation="horizontal">
  <input class="hcheckbox" type="checkbox" id="detailed-updates" name="detailed-updates" />
  <label class="hlabel" for="detailed-updates">
    Send me detailed updates about changes to reports and activity across every team in my account
  </label>
</div>

API reference

React

<Checkbox> renders the <input type="checkbox">. Put it in a horizontal Field for its label and description. Other props are the input's attributes.

Prop	Effect
`indeterminate`	Shows the mixed state

<CheckboxGroup> renders a Field that is the group, named by its label, and gives its checkboxes one name. Each checkbox in it takes a value.

Prop	Effect
`label`, `optional`, `description`, `error`	As for a Field
`name`	The name its checkboxes submit under; generated when left out
`value` or `defaultValue`	The checked checkboxes' values, as an array
`onValueChange`	Called with the checked values, in the checkboxes' order, when one changes
`disabled`	Disables every checkbox in it

HTML

An <input class="hcheckbox" type="checkbox"> with an id that its <label for> points to, or aria-labelledby. Load checkbox.css; field.css for its label.

Hook	Effect
`checked`	Checked
`indeterminate` (DOM property)	Mixed, shown as a dash; wins over checked
`disabled`	Dimmed, not-allowed cursor; its Field label turns gray
`--harmo-checkbox-size` on the element	Size (default 20px); the marks scale with it

A script is only needed for the mixed state, since indeterminate has no HTML attribute. See Checkbox's full contract.

Accessibility

A native checkbox: Space toggles it, and its <label> names it. A group of checkboxes goes in a Field with role="group" labelled by its .hlabel.