Checkbox

A versatile checkbox component with multiple variants, states, and sizes for creating accessible, user-friendly selection inputs.

Overview

The Checkbox component provides a versatile checkbox system that supports various styles, states, and interactive features. It's built with accessibility in mind and provides consistent interaction patterns across all variants, making it adaptable to any UI context while maintaining proper focus states and keyboard interactions.

Usage

import { Checkbox } from "@unkey/ui";
 
export default function MyComponent() {
  return (
    <div>
      <Checkbox variant="primary" color="success" />
      <Checkbox variant="outline" color="danger" />
      <Checkbox variant="ghost" size="lg" />
    </div>
  );
}

Examples

Basic Variants

Checkbox comes in three basic variants that serve different UI purposes:

Primary

The default checkbox style with a solid background when checked. Use for primary selection actions.

Outline

Checkbox with transparent background and visible border when checked. Ideal for secondary selection actions that don't require as much visual emphasis.

Ghost

Checkbox with no background when unchecked and subtle hover states. Perfect for tertiary selection actions or when space is limited.

Color Variants

Each checkbox variant can be combined with different color schemes to convey the nature of the selection:

Danger Variants

Primary

Outline

Ghost

Warning Variants

Primary

Outline

Ghost

Success Variants

Primary

Outline

Ghost

Info Variants

Primary

Outline

Ghost

Size Variants

All checkbox variants and color schemes can be combined with different sizes to fit various UI contexts.

With Labels

Checkbox components can be combined with labels for better user experience.

<div className="flex flex-col gap-6">
  <div>
    <h4 className="text-sm font-medium mb-2">Light</h4>
    <div className="flex flex-col gap-2">
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-terms" />
        <label
          htmlFor="checkbox-terms"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Accept terms and conditions
        </label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-disabled" disabled />
        <label
          htmlFor="checkbox-disabled"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Disabled option
        </label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-checked" checked />
        <label
          htmlFor="checkbox-checked"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Selected option
        </label>
      </div>
    </div>
  </div>

  <div>
    <h4 className="text-sm font-medium mb-2">Dark</h4>
    <div className="bg-black p-4 rounded-md flex flex-col gap-2 dark">
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-terms-dark" />
        <label
          htmlFor="checkbox-terms-dark"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Accept terms and conditions
        </label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-disabled-dark" disabled />
        <label
          htmlFor="checkbox-disabled-dark"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Disabled option
        </label>
      </div>
      <div className="flex items-center space-x-2">
        <Checkbox id="checkbox-checked-dark" checked />
        <label
          htmlFor="checkbox-checked-dark"
          className="text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        >
          Selected option
        </label>
      </div>
    </div>
  </div>
</div>

Checkbox Group

Checkboxes can be grouped together for related selection options.

Notification Preferences

Email notifications

SMS notifications

Push notifications

Features

Multiple Variants: Three basic variants (primary, outline, ghost) with different visual emphasis
Color Schemes: Five color options (default, danger, warning, success, info) for semantic meaning
Size Options: Multiple sizes for different contexts and touch targets
Interactive States: Hover, focus, checked, and disabled states
Accessibility: Full accessibility support with proper ARIA attributes
Responsive Design: Adapts to different screen sizes
Dark Mode Support: Consistent appearance in light and dark themes
Keyboard Support: Full keyboard navigation and shortcuts

Props

The Checkbox component accepts all standard HTML input attributes plus the following:

Prop	Type	Default	Description
`variant`	`"primary" \| "outline" \| "ghost"`	`"primary"`	The variant style to use for the checkbox
`color`	`"default" \| "success" \| "warning" \| "danger" \| "info"`	`"default"`	The color scheme to use for the checkbox
`size`	`"sm" \| "md" \| "lg" \| "xlg"`	`"md"`	The size of the checkbox
`checked`	`boolean`	-	Whether the checkbox is checked
`defaultChecked`	`boolean`	-	Default checked state when uncontrolled
`disabled`	`boolean`	-	Whether the checkbox is disabled
`required`	`boolean`	-	Required state for the checkbox
`name`	`string`	-	Name of the checkbox for form submission
`value`	`string`	-	Value of the checkbox for form submission
`onCheckedChange`	`(checked: boolean) => void`	-	Callback triggered when checkbox state changes
`className`	`string`	-	Additional CSS classes to apply

Variants

Primary

Solid background when checked
Use for primary selection actions
Default variant for most use cases

Outline

Transparent background with visible border when checked
Secondary selection actions with moderate emphasis
Good for forms and secondary actions

Ghost

No background when unchecked and subtle hover states
Tertiary selection actions or minimal visual impact
Perfect for dense UIs or subtle interactions

Color Schemes

Default

Neutral styling for general selections
Gray/blue color scheme
Most common choice for standard selections

Danger

Red color scheme for critical selections
Use for potentially destructive or critical operations
Should be used sparingly and with clear intent

Warning

Yellow/orange color scheme for cautionary selections
Use for selections that require attention but aren't destructive
Good for confirmations or warnings

Success

Green color scheme for positive selections
Use for confirming or positive operations
Encourages positive user actions

Info

Blue color scheme for informational selections
Use for neutral or informational operations
Good for educational or informational contexts

Structure

The Checkbox component is a self-contained component that renders as a single checkbox element with appropriate styling, accessibility attributes, and optional icon support.

Styling

The Checkbox component includes default styling with:

Consistent sizing and border radius across variants
Color-coded schemes for semantic meaning
Smooth transitions for state changes
Dark mode support
Responsive design
Focus states for accessibility
Customizable through className prop

Custom Styling

You can customize the appearance using the className prop:

<Checkbox 
  variant="primary"
  color="success"
  className="custom-checkbox-class"
/>

Accessibility

The Checkbox component is built with accessibility in mind:

Semantic HTML: Uses proper checkbox element with appropriate roles
ARIA Attributes: Proper ARIA labels and states for screen readers
Keyboard Navigation: Full keyboard support including Tab and Space
Focus Management: Clear focus indicators and logical tab order
Screen Reader Support: Announces checkbox states and actions appropriately
High Contrast: Maintains proper contrast ratios across all variants

Checkbox

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Light

Dark

Notification Preferences

On this page