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. |
| className | string | — | Additional class name for Checkbox.Root. |
| 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. |
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).
Related
Playground
<Checkbox label="Agree to the terms" />