InputsReact

Checkbox

An easily stylable checkbox.

Rendered by React 19.3.1

Loading React…

import * as React from 'react'
import { Checkbox } from '@hamur/react/checkbox'

export default function CheckboxExample() {
  const [accepted, setAccepted] = React.useState(false)
  return (
    <div className="stack">
      <label className="row">
        <Checkbox.Root className="checkbox" onCheckedChange={setAccepted}>
          <Checkbox.Indicator className="checkbox-indicator">
            ✓
          </Checkbox.Indicator>
        </Checkbox.Root>
        Accept the terms
      </label>
      <label className="row">
        <Checkbox.Root className="checkbox" defaultChecked>
          <Checkbox.Indicator className="checkbox-indicator">
            ✓
          </Checkbox.Indicator>
        </Checkbox.Root>
        Send me updates
      </label>
      <label className="row">
        <Checkbox.Root className="checkbox" disabled>
          <Checkbox.Indicator className="checkbox-indicator">
            ✓
          </Checkbox.Indicator>
        </Checkbox.Root>
        Disabled
      </label>
      <p className="muted">The terms are {accepted ? 'accepted' : 'not accepted'}</p>
    </div>
  )
}

270Tests passing in React · 0 failing

10.4 KiBSize

Not measured yetMemory

Not measured yetSpeed

productdevbook and 18 upstream authors14 commits · last Nov 3

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<Checkbox.Root>
  <Checkbox.Indicator />
</Checkbox.Root>

Examples

The demo at the top is the one example this component has so far.

API reference

16 props across 2 parts, in React syntax. className, style, render are listed once, under Shared props.

Indicator`Checkbox.Indicator`

Indicates whether the checkbox is ticked. Renders a <span>.

Indicator props
Prop	Type	Default
`keepMounted`Whether to keep the element in the DOM when the checkbox is not checked.	`boolean`	`false`

Indicator data attributes
Data attribute	Description
`data-checked`	Present when the checkbox is checked.
`data-unchecked`	Present when the checkbox is not checked.
`data-indeterminate`	Present when the checkbox is in an indeterminate state.
`data-disabled`	Present when the checkbox is disabled.
`data-readonly`	Present when the checkbox is readonly.
`data-required`	Present when the checkbox is required.
`data-starting-style`	Present when the checkbox indicator begins animating in.
`data-ending-style`	Present when the checkbox indicator is animating out.
`data-valid`	Present when the checkbox is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the checkbox is in an invalid state (when wrapped in Field.Root).
`data-touched`	Present when the checkbox has been touched (when wrapped in Field.Root).
`data-dirty`	Present when the checkbox's value has changed (when wrapped in Field.Root).
`data-filled`	Present when the checkbox is checked (when wrapped in Field.Root).
`data-focused`	Present when the checkbox is focused (when wrapped in Field.Root).

Root`Checkbox.Root`

Represents the checkbox itself. and a hidden <input> beside. Renders a <span>.

Root props
Prop	Type	Default
`name`Identifies the field when a form is submitted.	`string`	`undefined`
`defaultChecked`Whether the checkbox is initially ticked.	`boolean`	`false`
`checked`Whether the checkbox is currently ticked.	`boolean`	`undefined`
`onCheckedChange`Event handler called when the checkbox is ticked or unticked.	`((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)`	`—`
`indeterminate`Whether the checkbox is in a mixed state: neither ticked, nor unticked.	`boolean`	`false`
`value`The checkbox's value.	`string`	`—`
`form`Identifies the form that owns the hidden input.	`string`	`—`
`nativeButton`Whether the component renders a native `<button>` element when replacing it	`boolean`	`false`
`parent`Whether the checkbox controls a group of child checkboxes.	`boolean`	`false`
`uncheckedValue`The value submitted with the form when the checkbox is unchecked.	`string`	`—`
`disabled`Whether the component should ignore user interaction.	`boolean`	`false`
`readOnly`Whether the user should be unable to tick or untick the checkbox.	`boolean`	`false`
`required`Whether the user must tick the checkbox before submitting a form.	`boolean`	`false`
`inputRef`A ref to access the hidden `<input>` element.	`React.Ref<HTMLInputElement>`	`—`
`id`The id of the input element.	`string`	`—`

Root data attributes
Data attribute	Description
`data-checked`	Present when the checkbox is checked.
`data-unchecked`	Present when the checkbox is not checked.
`data-indeterminate`	Present when the checkbox is in an indeterminate state.
`data-disabled`	Present when the checkbox is disabled.
`data-readonly`	Present when the checkbox is readonly.
`data-required`	Present when the checkbox is required.
`data-valid`	Present when the checkbox is in a valid state (when wrapped in Field.Root).
`data-invalid`	Present when the checkbox is in an invalid state (when wrapped in Field.Root).
`data-touched`	Present when the checkbox has been touched (when wrapped in Field.Root).
`data-dirty`	Present when the checkbox's value has changed (when wrapped in Field.Root).
`data-filled`	Present when the checkbox is checked (when wrapped in Field.Root).
`data-focused`	Present when the checkbox is focused (when wrapped in Field.Root).

Shared props

Every part that renders an element takes these.

Shared props
Prop	Type
`className`CSS class applied to the element, or a function that returns a class based on the component's state.	`string \| ((state: State) => string \| undefined)`
`style`Style applied to the element, or a function that returns a style object based on the component's state.	`React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined)`
`render`Allows you to replace the component's HTML element with a different tag, or compose it with another component.	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, State>`

Keyboard and accessibility

Keyboard

Keyboard
Keys	Does	Part
`Space`	Checks or unchecks the box	Root
`Enter`	Does not toggle; submits the form the checkbox belongs to, as a native checkbox does	Root

Accessibility

What the parts set
Part	Sets	So that
Root	`role="checkbox"`, `aria-checked` (`"mixed"` while `indeterminate`)	a screen reader reads it as a checkbox and its state
Root	`aria-readonly`, `aria-required` from `readOnly` and `required`	the constraints are announced
Root	`aria-labelledby` to an associated label	a `<label>` or Field.Label names the checkbox
Root	a hidden `<input type="checkbox">` with `aria-hidden="true"` and `tabindex="-1"`	the form gets the value without a second control to read or tab to
Indicator	renders a `<span>` with your mark	the tick is decoration; the state is on Root

Focus order

Root is one tab stop. The hidden input is skipped.