Checkbox
checkboxToggles an independent boolean value with an indeterminate state.
Usage
Basic usage
label renders the text on the right side of the box and is natively associated, and you can switch it by clicking on the text.
<Checkbox label="Agree to the terms" />Selected by default
The uncontrolled writing method is checked by default with defaultChecked.
<Checkbox defaultChecked label="Remember Me" />Three states: half-selected
indeterminate renders horizontal bars, often used for "select all" parent items.
<>
<Checkbox indeterminate label="Half Select" />
<Checkbox defaultChecked label="Selected" />
<Checkbox label="Not selected" />
</>Disabled
disabled Reduce transparency and block interaction (selected state can also be disabled).
<>
<Checkbox disabled label="Disabled" />
<Checkbox disabled defaultChecked label="Disable selected" />
</>Compatible with Field
Put it into Field to automatically concatenate labels and error messages.
<Field label="Terms of Service" error="Must check to continue" className="w-72">
<Checkbox label="I have read and agree" />
</Field>When to use
Use Checkbox for a single Boolean choice such as accepting terms or remembering a login, or for a Select All control with an indeterminate state. Wrap coordinated options in CheckboxGroup to manage them as a value array. Use Switch for an immediate on/off setting or Radio for mutually exclusive choices.
Import
import { Checkbox } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| checked | boolean | - | Controlled checked state. |
| defaultChecked | boolean | - | Initial checked state when uncontrolled. |
| indeterminate | boolean | false | Third, partially checked state provided by Base UI. |
| disabled | boolean | false | Disables the checkbox. |
| required | boolean | false | Marks the checkbox as required. |
| name | string | - | Form field name. |
| value | string | - | Form value and the member key used by CheckboxGroup. |
| id | string | - | ID associated with the label. |
| size | "sm" | "md" | "md" | Size step; the box and its built-in check scale together. md is 20px/14px/text-sm, sm is 16px/12px/text-xs, matching size="sm" on Input and SelectTrigger. |
| className | string | - | Additional class name for Checkbox.Root (the box); it cannot reach the label text. |
| labelClassName | string | - | Applied to the label <span> for font size and color. |
| tabIndex | number | - | Passed to Checkbox.Root. Set -1 in a tree when a roving-focus container owns keyboard focus. |
| aria-label | string | - | Accessible label when no visible label is provided. |
Events
| Event | Type | Description |
|---|---|---|
| onCheckedChange | (checked: boolean) => void | Called when checked state changes. HulianUI normalizes the signature and omits eventDetails. |
Slots
| Slot | Type | Description |
|---|---|---|
| label | ReactNode | Inline label rendered to the right with a native <label> association. |
| children | ReactNode | Equivalent to label: <Checkbox>I agree</Checkbox>. When both are given, label wins. |
Usage guidelines
- Inside CheckboxGroup, every Checkbox must provide
value, notname. See [[base-ui-checkbox-group-matches-members-by-value-not-name]]: Base UI rc.0 matches group members byvalue; usingnamemakesdefaultValue,value, andonValueChangefail silently even though the boxes render. indeterminateis an independent third state. After the user clicks, usually resolve it explicitly withsetIndeterminate(false).- Wrapping the Checkbox in your own
<label>does work, so there is no need to forwardonClickby hand. The Root renders as<span role="checkbox">, which is not a labelable element, so the DOM makes implicit association look broken, but Base UI keeps a visually hidden native input inside to carry activation, and clicking the text still toggles. Use this when the typography is too specific forsizepluslabelClassName. - Do not add
<label htmlFor>pointing at the Rootidwhile also wrapping: an explicithtmlForoverrides that implicit association, and having both means clicking the text does nothing at all. Wrap, or usehtmlFor, but not both.
Related
Playground
<Checkbox label="Agree to the terms" />