ComponentsFormCheckbox

Checkbox

6 colors · 3 sizes · card style · CheckboxGroup with select all

StatesColorsSizesCard styleCheckboxGroupSelect all

Overview

6 colors · 3 sizes · card style · CheckboxGroup with select all

Default checkbox

Live preview

Use a checkbox when someone can independently turn an option on or off. The choice takes effect when the surrounding form is submitted.

App.tsx
tsx
import { Checkbox } from 'omverse-ui'
 
<Checkbox
label="Email notifications"
helperText="Receive product updates and account activity"
defaultChecked
/>

Checkboxes support independent binary choices and multi-select groups. Use a radio group when only one option can be selected.

Write labels as positive statements so the checked state is easy to understand, such as “Email notifications” instead of “Do not disable email.”

Anatomy

  • Root container and spacing boundary.
  • Primary content and optional secondary metadata.
  • State indicators and utility affordances (icons, badges, controls).
  • Optional helper text, grouping, and behavioral wrappers.

When to use

  • Choose Checkbox when a repeated, structured interaction is required.
  • Use it for clear, consistent operations across similar surfaces.
  • Use in forms, lists, and action workflows where clarity matters.

When not to use

  • Do not use only for decorative layout without interaction meaning.
  • Avoid duplicating the same behavior without distinct user context.
  • Prefer simpler HTML or textual content for static, non-interactive labels.

Variants

Component variants should be documented by API props and examples below.

States

Common states include idle, active, disabled, focused, and loading/pending states where applicable.

Behavior

Behavior should remain deterministic and keyboard-friendly, with clear visual feedback for every state transition.

Accessibility

  • Use semantic structure and visible labels whenever possible.
  • Preserve keyboard navigation and focus visibility.
  • Announce status and changes when context requires it.

Content guidelines

  • Prefer short, clear labels.
  • Keep content actions scannable and outcome-oriented.
  • Use consistent wording across similar components.

Examples

States

Live preview

Unchecked, checked, indeterminate, disabled, and disabled checked

App.tsx
tsx
<Checkbox label="Unchecked" />
<Checkbox label="Checked" defaultChecked />
<Checkbox label="Indeterminate" indeterminate />
<Checkbox label="Disabled" disabled />
<Checkbox label="Disabled checked" disabled defaultChecked />

Colors

Live preview

Six color variants — default, secondary, success, warning, error, and info

App.tsx
tsx
<Checkbox label="Default (primary)" color="default" defaultChecked />
<Checkbox label="Secondary" color="secondary" defaultChecked />
<Checkbox label="Success" color="success" defaultChecked />
<Checkbox label="Warning" color="warning" defaultChecked />
<Checkbox label="Error" color="error" defaultChecked />
<Checkbox label="Info" color="info" defaultChecked />

Sizes

Live preview

sm, md (default), and lg checkbox sizes

App.tsx
tsx
<Checkbox label="Small" size="sm" defaultChecked />
<Checkbox label="Medium (default)" size="md" defaultChecked />
<Checkbox label="Large" size="lg" defaultChecked />

Shape

Live preview

Square (rounded corners, default) or circle shape

App.tsx
tsx
<Checkbox label="Square (default)" shape="square" defaultChecked />
<Checkbox label="Circle" shape="circle" defaultChecked />

With helper + error

Live preview

Helper text shown below the label; error state with message and required indicator

You must accept the terms to continue

App.tsx
tsx
<Checkbox
label="Email notifications"
helperText="Receive product updates and announcements"
defaultChecked
/>
 
{/* Controlled with error */}
const [terms, setTerms] = useState(false)
 
<Checkbox
label="Accept terms and conditions"
required
error={!terms}
errorText="You must accept the terms to continue"
checked={terms}
onChange={e => setTerms(e.target.checked)}
/>

Card style

Live preview

Bordered card layout — ideal for plan selection and feature toggles

App.tsx
tsx
const [plan, setPlan] = useState('pro')
 
<Checkbox
card
label="Pro plan"
description="$12/month · Unlimited projects · Priority support"
checked={plan === 'pro'}
onChange={() => setPlan('pro')}
/>
<Checkbox
card
label="Team plan"
description="$49/month · Up to 10 members · Admin controls"
checked={plan === 'team'}
onChange={() => setPlan('team')}
/>
<Checkbox
card
label="Enterprise"
description="Custom pricing · Unlimited members · SLA"
checked={plan === 'enterprise'}
onChange={() => setPlan('enterprise')}
/>
<Checkbox
card
label="Unavailable plan"
description="This option is currently disabled"
disabled
/>

CheckboxGroup — select all

Live preview

Managed group with auto indeterminate state on the select-all parent

User permissions

Selected: read, write

App.tsx
tsx
const [permissions, setPermissions] = useState(['read', 'write'])
 
<CheckboxGroup
legend="User permissions"
selectAll
selectAllLabel="All permissions"
value={permissions}
onChange={setPermissions}
>
<Checkbox value="read" label="Read" helperText="View all content" />
<Checkbox value="write" label="Write" helperText="Create and edit content" />
<Checkbox value="delete" label="Delete" helperText="Remove content permanently" />
<Checkbox value="admin" label="Admin" helperText="Full system access" />
</CheckboxGroup>
 
<p>Selected: {permissions.join(', ') || 'none'}</p>

Checkbox props

CheckboxGroup props

Props / API

Api Props

Props

PropTypeDefaultDescription
labelReactNode—Label text shown next to the checkbox
helperTextstring—Helper text shown below the label
requiredbooleanfalseMarks as required — adds * to label
errorbooleanfalseError state — red border
errorTextstring—Error message shown when error=true
indeterminatebooleanfalseShows a dash instead of checkmark
cardbooleanfalseWraps the checkbox in a bordered card
descriptionstring—Description inside the card (card=true only)
size'sm' | 'md' | 'lg''md'Size of the checkbox
shape'square' | 'circle''square'Shape of the checkbox
color'default' | 'secondary' | 'success' | 'warning' | 'error' | 'info''default'Color when checked
disabledbooleanfalseDisables the checkbox
checkedboolean—Controlled checked state
defaultCheckedbooleanfalseUncontrolled initial checked state
onChangeReact.ChangeEventHandler<HTMLInputElement>—Change event callback
legendstring—Group label shown above the checkboxes
valuestring[]—Controlled selected values
onChange(value: string[]) => void—Callback fired when selection changes
selectAllbooleanfalseShows a select-all checkbox with auto indeterminate state
selectAllLabelstring'Select all'Label for the select all checkbox
color'default' | 'secondary' | 'success' | 'warning' | 'error' | 'info'—Color applied to all child checkboxes
size'sm' | 'md' | 'lg'—Size applied to all child checkboxes
childrenReactNode—Checkbox components with a value prop