Checkbox
Checkboxes allow users to select one or more options from a list, enable settings, or confirm acknowledgement of information.
Quick Start
Use a Checkbox to allow users to make a binary choice.
1import { Checkbox } from "@ecos/ui"; 2 3<Checkbox 4 label="Email notifications" 5/>
Controlled Usage
Checkbox state can be controlled externally using the checked and onCheckedChange props.
1const [checked, setChecked] = useState(false); 2 3<Checkbox 4 label="Accept terms and conditions" 5 checked={checked} 6 onCheckedChange={setChecked} 7/>
Labels
Provide a label to clearly communicate the purpose of the checkbox.
1<Checkbox 2 label="Subscribe to newsletter" 3/>
Help Text
Use helpText to provide additional guidance or context.
Receive product updates and announcements.
1<Checkbox 2 label="Email notifications" 3 helpText="Receive product updates and announcements." 4/>
States
Use the state prop to communicate validation and feedback states.
You must accept the terms before continuing.
Terms accepted.
1<Checkbox 2 label="Terms and conditions" 3 state="error" 4 helpText="You must accept the terms before continuing." 5/> 6 7<Checkbox 8 label="Terms and conditions" 9 state="success" 10 helpText="Terms accepted." 11 checked 12/>
Required Fields
Use the required prop to indicate mandatory selections.
1<Checkbox 2 label="I agree to the terms and conditions" 3 required 4/>
Disabled State
Checkboxes can be disabled when interaction is unavailable.
1<Checkbox 2 label="Disabled option" 3 disabled 4/>
Multiple Selection
Checkboxes are commonly used as groups to allow multiple selections.
1<div className="space-y-2"> 2 <Checkbox label="Email notifications" /> 3 4 <Checkbox label="SMS notifications" /> 5 6 <Checkbox label="Push notifications" /> 7</div>
Custom IDs
Supply an id when integrating with forms or analytics.
1<Checkbox 2 id="marketing-emails" 3 label="Marketing emails" 4/>
Checkbox Without Label
Checkboxes can be rendered without a label when paired with custom layouts.
1<Checkbox />
API Reference
Property | Type | Default | Description |
|---|---|---|---|
| label | string | - | Label displayed alongside the checkbox. |
| helpText | string | - | Additional descriptive text displayed below the checkbox. |
| state | "default" | "error" | "success" | "default" | Controls the validation state styling applied to the label and help text. |
| required | boolean | false | Displays a required indicator alongside the label. |
| id | string | "checkbox-" + label | Unique identifier used to associate the label with the checkbox. |
| checked | boolean | 'indeterminate' | - | Controls the checked state of the checkbox. |
| defaultChecked | boolean | false | Sets the initial checked state when uncontrolled. |
| onCheckedChange | (checked) => void | - | Called when the checked state changes. |
| disabled | boolean | false | Prevents user interaction. |
| className | string | - | Additional classes applied to the checkbox root element. |
Visual Reference
Configuration | Preview |
|---|---|
| Default | |
| With Help Text | Receive product updates and announcements. |
| Error State | You must accept the terms before continuing. |
| Success State | Terms accepted. |
| Checked | |
| Indeterminate | |
| Required | |
| Disabled | |
| Disabled - Checked | |
| Without Label |