Checkbox

Import

import { Checkbox } from '@envsemble/envui';

Usage

A Checkbox is a native checkbox inside its <label>, named by label; an optional description is a short muted line under it, read with its name.

Uncontrolled: defaultChecked.
Controlled: checked and onCheckedChange, which receives the new state as a boolean.

IncludeArchived.tsx

import { useState } from 'react';
import { Checkbox } from '@envsemble/envui';

export default function IncludeArchived() {
  const [included, setIncluded] = useState(false);
  return (
    <Checkbox label="Include archived projects" checked={included} onCheckedChange={setIncluded} />
  );
}

Mixed and select all

checked="mixed" shows a dash, for a parent whose children are partly chosen; pressing a mixed checkbox reports true. The checkbox doesn't derive it: set the parent's checked from its children, true when all are checked, 'mixed' when some are and false when none are, as the SelectAll example does.

<Checkbox
  label="All projects"
  checked={selected.every(Boolean) ? true : selected.some(Boolean) ? 'mixed' : false}
  onCheckedChange={(checked) => setSelected(selected.map(() => checked))}
/>

In a form

A checked box submits its name with its value; an unchecked one submits nothing. A reset restores defaultChecked. new FormData(form).getAll('notify') reads the values of a group's checked boxes. envUI has no checkbox group yet: name a group with a native fieldset and its legend, which is read with each choice.

<form onSubmit={save}>
  <fieldset>
    <legend>Send me an e-mail about</legend>
    <Checkbox name="notify" value="mentions" label="Mentions" defaultChecked />
    <Checkbox name="notify" value="digest" label="A weekly digest" />
  </fieldset>
  <Button type="submit">Save preferences</Button>
</form>

Composition

className and style reach the root, env-checkbox, the label around the box and the text; ref and the other native props, such as name and required, reach the input, env-checkbox-input, so a form library can register and focus it. The box is env-checkbox-box, the check env-checkbox-indicator and the text env-checkbox-label.

Accessibility

You provide

A label, or aria-label on a checkbox without one.
A name for a group, such as a fieldset's legend.
An error or description, linked with aria-describedby.

envUI provides

A native checkbox inside its <label>, named by the label's text.
The mixed state as indeterminate and aria-checked="mixed".
A focus outline, and a 2.75 rem target on touch screens.

Props

A native checkbox inside its label, checked, unchecked or mixed.

Prop	Type	Description
`ref`	`Ref<HTMLInputElement>`	The native checkbox, so that a form library can register it and focus it; the other native props, such as name and required, reach it too.
`className`	`string`	The checkbox's class, on its root element, the label around the box and the text.
`style`	`CSSProperties`	Styles of the root element.
`label`	`ReactNode`	The text beside the box, which names the checkbox; pressing it toggles the checkbox.
`description`	`ReactNode`	A short, muted line under the label, such as what the option changes. It is part of the checkbox's label, so it is read with its name.
`checked`	`boolean'mixed'`	Whether the box is checked, unchecked or "mixed", for a parent whose children are partly chosen. With `onCheckedChange` it controls the checkbox.
`defaultChecked`Default `false`	`boolean'mixed'`	How an uncontrolled checkbox starts, and what a form reset restores; unchecked by default.
`onCheckedChange`	`(checked: boolean) => void`	Called with the new state when people press the checkbox; a mixed checkbox reports true.

Also accepts the native props of <input>, such as ref, className and aria-* attributes.

Part names

Each part's class and state attributes are public and versioned, for an application's CSS to style.

env-checkbox: The checkbox with its label.
env-checkbox-box: The box that shows the state.
env-checkbox-description: The muted line under the label.
env-checkbox-indicator: The check or dash inside the box.
env-checkbox-input: The native input.
env-checkbox-label: The label.

Color properties

Each sets a color of one instance, through style or CSS; its hover, focus and press follow it. They are public and versioned.

--env-checkbox-outline: The box's edge while unchecked.
--env-checkbox-selected: The box's fill while checked or indeterminate; set, it takes state layers instead of the designed hover and press fills.
--env-checkbox-selected-content: The check mark or dash, and the color of the state layers.

Changelog

1.0.0: className and style style the root, env-checkbox, rather than the input, which keeps ref and the other native props. The classes follow the component: env-choice-control is env-checkbox, env-checkbox-control env-checkbox-input and env-checkbox-mark env-checkbox-indicator.
1.0.0-prerelease.6: The check mark settles in from a little smaller, and fades out as the box is cleared; the box fills and empties with it, from the first frame.

A checked or mixed box that is unavailable takes the neutral fill, with its mark in --env-color-fg-disabled, rather than a faded accent, as an unavailable button does. A read-only box, with aria-readonly, keeps its colors and doesn't answer the pointer.

Beside a label that wraps or has a description, the box sits on the middle of its first line rather than across both lines.

Under the pointer and while pressed, a halo of the shared state layer rings the box, checked or not, a step stronger while pressed; an unchecked box's edge also darkens to the text color, and the box stays empty, so it doesn't read as a checked one that is unavailable.
1.0.0-prerelease.5: description, a muted line under the label.