Checkbox
A binary or mixed selection control with a native form value.
Contract
| Decision | Choose |
|---|---|
| selection | unchecked, checked, or indeterminate for a partially selected set |
| availability | enabled, readOnly when focus and form value must remain, or disabled when unavailable |
| size | md or lg; default md |
| form | name, value, uncheckedValue, form, required, and native reset |
Give every checkbox a visible label or accessible name. Wrap the control and a TRField.Label in a TRField.Item to get a clickable visible label; the item scopes the label to the control inside it, so no id or htmlFor wiring is needed. Every TRField.Item needs a TRField.Root ancestor, so wrap the item — or the whole group — in one TRField.Root. Use a checkbox for an independent or batched choice; use TRCheckboxGroup to coordinate several checkbox values.
Install
pnpm add @tinyrack/uiScroll inside the code area to read long lines.
Styles
@import '@tinyrack/ui/components/checkbox.css';Scroll inside the code area to read long lines.
Imports
import { TRCheckbox } from '@tinyrack/ui/components/checkbox';Scroll inside the code area to read long lines.
Playground
Usage
Examples
Choose a selection state
Unchecked, checked, and mixed permalink
Use mixed only when the checkbox summarizes a partially selected set.
Match the control density
Keep or remove interaction
Editable, read only, and disabled permalink
Read-only controls stay focusable and keep their form value; disabled controls leave the tab order and submission.
Require an agreement
Submit explicit on and off values
External form ownership permalink
Use `form` to associate the hidden input with another form and `uncheckedValue` when the off state must also serialize.
API
Selection and interaction
| Prop | Type / default | Purpose |
|---|---|---|
checked, defaultChecked | boolean, false | Controls or initializes selection. |
indeterminate | boolean, false | Exposes the mixed state; clear it when a user resolves the choice. |
onCheckedChange | (checked, details) => void | Reports an attempted change. |
disabled, readOnly | boolean, false | Removes interaction, or keeps a focusable immutable value. |
uiSize | 'md' | 'lg', 'md' | Sets the visual control size. |
Forms and composition
name, value, uncheckedValue, form, required, and inputRef are forwarded to the hidden native checkbox. Uncontrolled roots restore defaultChecked on owner-form reset; controlled roots remain governed by checked. render, root ref, event props, and state-driven className and style follow Base UI composition.
TRCheckbox.Indicator renders for checked or mixed state. Its render callback receives state.indeterminate; keepMounted keeps it in the DOM for transitions. Root and Indicator expose relevant data-checked, data-unchecked, data-indeterminate, data-disabled, data-readonly, and data-invalid attributes.
The module exports TRCheckbox, both named parts, their prop and state types, and TRCheckboxUiSize. CSS is opt-in.