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
checkedandonChangeto control it, ordefaultCheckedto let the native input keep its own state. - Pass
labelto render a visible label row. Withoutlabeloraria-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
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Controlled checked state |
defaultChecked | boolean | — | Initial state when uncontrolled |
onChange | ChangeEventHandler<HTMLInputElement> | — | Change handler |
indeterminate | boolean | false | Shows a dash instead of the check mark and sets aria-checked="mixed" |
label | ReactNode | — | Text beside the control. Renders a label row whose whole area toggles the checkbox |
description | ReactNode | — | 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 |
disabled | boolean | false | Disables interaction and applies the disabled visual style |
required | boolean | — | Marks the underlying input as required |
size | 'xs' | 'sm' | 'md' | 'lg' | 'sm' | Size of the checkbox box and its check mark |
slots.checkMark | ReactNode | — | Overrides the default check-mark icon |
slotProps.inputRoot | BaseHTMLProps<HTMLDivElement> | — | Props for the outer container div |
slotProps.checkMark | BaseHTMLProps<HTMLDivElement> | — | Props for the check-mark wrapper div |
slotProps.row | BaseHTMLProps<HTMLLabelElement> | — | Props for the label row. Only rendered with label |
slotProps.label | BaseHTMLProps<HTMLSpanElement> | — | Props for the label text |
slotProps.description | BaseHTMLProps<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
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)
| Slot | Type | Description |
|---|---|---|
checkMark | ReactNode | Icon override rendered inside the check-mark wrapper when checked |
| Slot Prop | Props | Description |
|---|---|---|
inputRoot | BaseHTMLProps<HTMLDivElement> | The outer container div that holds the input and check mark |
checkMark | BaseHTMLProps<HTMLDivElement> | The check-mark wrapper div shown when checked is true |
row | BaseHTMLProps<HTMLLabelElement> | The <label> row rendered when label is set |
label | BaseHTMLProps<HTMLSpanElement> | The label text |
description | BaseHTMLProps<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 througharia-labelledbyand described bydescriptionthrougharia-describedby. Your ownaria-label,aria-labelledbyandaria-describedbystill take precedence or are joined. - Without
label, it falls back to a translated defaultaria-labelwhen none is provided, so the control is never unlabeled — but prefer a descriptivearia-label. indeterminatesetsaria-checked="mixed".- The check-mark icon is
aria-hidden, since the checked state is already conveyed by the native input's checked property. disableduses the container'sinertattribute alongside the nativedisabledattribute, removing the control from the accessibility tree and tab order.