docs / core / checkbox

Checkbox

the collecting control. it gathers choices and waits for a submit, ticking one commits nothing until you send the form. that deferral is the whole line between it and Switch.

intensity · recedesrsc · client

provenance

authored in usva

layer

core / primitives

intensity

recedes · safe anywhere, including dense surfaces

composition

forms, settings rows, filter groups. anywhere choices accumulateindeterminate heads a group whose children disagreenot for actions that apply immediately. that is a switch, not a checkboxnever unlabelled. the label is the click target and the accessible name

a11y

role="checkbox" named by its label · disabled sets aria-disabled · the check icon is aria-hiddenjest-axe

dependencies

@base-ui/react · class-variance-authority
live demo · try it out

You agree to our terms of service and privacy policy.

customize
labelthe click target and accessible name
descriptionhelper text under the control
sizesm for dense rows
defaultCheckedstarts ticked
indeterminatethe mixed state for a group head
disabledgreys out the whole field
usagecopy
import { Checkbox } from "@usva-ui/react/primitives/checkbox";

<Checkbox
  label="Accept terms"
  description="You agree to our terms of service and privacy policy."
/>

props

proptypedefaultnotes
checkedboolean—controlled checked state.
defaultCheckedbooleanfalseinitial checked state when uncontrolled.
onCheckedChange(checked: boolean) => void—fires with the next checked state.
indeterminatebooleanfalsethe mixed state, for a parent whose children disagree.
disabledbooleanfalsedisables the whole field, label included.
labelReactNode—the field label, wired to the control by id.
descriptionReactNode—helper text under the control.
size"sm" | "md""md"sm for dense rows. the hidden hit area grows to compensate.

get it

bun add @usva-ui/reactcopy
usagecopy
import { Checkbox } from "@usva-ui/react/primitives/checkbox";

<Checkbox
  label="Accept terms"
  description="You agree to our terms of service."
/>