UnflowUI
Components

Checkbox

A styled native checkbox input with size variants, an optional label row and a customizable check mark.

Overview

Checkbox wraps a native <input type="checkbox"> in a small square container that draws the checked/unchecked/disabled visuals via CSS, and shows a check-mark icon on top of the input when checked. Because it's a real checkbox, it participates in forms and works with standard React controlled-state patterns.

Two implementation notes worth knowing:

  • Pass checked and onChange to control it, or defaultChecked to let the native input keep its own state.
  • Pass label to render a visible label row. Without label or aria-label, Checkbox falls back to a translated default label so it's never unlabeled for assistive tech — but a descriptive name is strongly recommended.

Import

import { Checkbox } from '@unflowio/ui/components/Checkbox';

Props

PropTypeDefaultDescription
checkedboolean—Controlled checked state
defaultCheckedboolean—Initial state when uncontrolled
onChangeChangeEventHandler<HTMLInputElement>—Change handler
indeterminatebooleanfalseShows a dash instead of the check mark and sets aria-checked="mixed"
labelReactNode—Text beside the control. Renders a label row whose whole area toggles the checkbox
descriptionReactNode—Secondary text under the label, announced as the accessible description. Needs label
labelPlacement'start' | 'end''end'Where the text sits. start puts the checkbox at the end of a full-width row
disabledbooleanfalseDisables interaction and applies the disabled visual style
requiredboolean—Marks the underlying input as required
size'xs' | 'sm' | 'md' | 'lg''sm'Size of the checkbox box and its check mark
slots.checkMarkReactNode—Overrides the default check-mark icon
slotProps.inputRootBaseHTMLProps<HTMLDivElement>—Props for the outer container div
slotProps.checkMarkBaseHTMLProps<HTMLDivElement>—Props for the check-mark wrapper div
slotProps.rowBaseHTMLProps<HTMLLabelElement>—Props for the label row. Only rendered with label
slotProps.labelBaseHTMLProps<HTMLSpanElement>—Props for the label text
slotProps.descriptionBaseHTMLProps<HTMLSpanElement>—Props for the description text

className is applied directly to the <input> element (not the container) — use slotProps.inputRoot/slotProps.checkMark to style the wrapper or the check mark. All standard HTMLInputElement props (id, name, value, onBlur, aria-label, etc.) are forwarded to the input.

Sizes

<Checkbox checked onChange={() => {}} size="xs" aria-label="Extra small" />
<Checkbox checked onChange={() => {}} size="sm" aria-label="Small" />
<Checkbox checked onChange={() => {}} size="md" aria-label="Medium" />
<Checkbox checked onChange={() => {}} size="lg" aria-label="Large" />

States

unchecked
checked
disabled unchecked
disabled checked
const [checked, setChecked] = useState(false);

<Checkbox checked={checked} onChange={(e) => setChecked(e.target.checked)} aria-label="Toggle" />
<Checkbox checked={false} disabled aria-label="Disabled unchecked" />
<Checkbox checked={true} disabled aria-label="Disabled checked" />

With a label

label renders the checkbox in a label row; clicking anywhere on the row toggles it. Add description for secondary text, and set labelPlacement="start" to put the text first and the checkbox at the end of a full-width row.

<Checkbox
  checked={digest}
  onChange={(e) => setDigest(e.target.checked)}
  label="Weekly digest"
  description="A summary of activity every Monday"
/>
<Checkbox
  checked={mentions}
  onChange={(e) => setMentions(e.target.checked)}
  label="Mentions only"
  labelPlacement="start"
/>
<Checkbox checked disabled label="Security alerts" description="Always on" />

Indeterminate

Use indeterminate for a parent checkbox whose children are partly selected.

<Checkbox checked={false} indeterminate onChange={() => {}} label="Select all" />

Custom check mark

Swap the default check icon via slots.checkMark.

import { useState } from 'react';
import { Heart } from '@unflowio/icons/games/heart';

const [favorite, setFavorite] = useState(true);

<Checkbox
  checked={favorite}
  onChange={(e) => setFavorite(e.target.checked)}
  slots={{ checkMark: <Heart variant="Fill" /> }}
  aria-label="Favorite"
/>

Customization (slots & slotProps)

SlotTypeDescription
checkMarkReactNodeIcon override rendered inside the check-mark wrapper when checked
Slot PropPropsDescription
inputRootBaseHTMLProps<HTMLDivElement>The outer container div that holds the input and check mark
checkMarkBaseHTMLProps<HTMLDivElement>The check-mark wrapper div shown when checked is true
rowBaseHTMLProps<HTMLLabelElement>The <label> row rendered when label is set
labelBaseHTMLProps<HTMLSpanElement>The label text
descriptionBaseHTMLProps<HTMLSpanElement>The description text

Accessibility

  • Renders a real <input type="checkbox">, so it's natively keyboard-operable (Space to toggle) and participates in form submission.
  • With label, the input is named by the label text through aria-labelledby and described by description through aria-describedby. Your own aria-label, aria-labelledby and aria-describedby still take precedence or are joined.
  • Without label, it falls back to a translated default aria-label when none is provided, so the control is never unlabeled — but prefer a descriptive aria-label.
  • indeterminate sets aria-checked="mixed".
  • The check-mark icon is aria-hidden, since the checked state is already conveyed by the native input's checked property.
  • disabled uses the container's inert attribute alongside the native disabled attribute, removing the control from the accessibility tree and tab order.