Checkbox

The Checkbox component is an enhanced checkbox with beautiful animations and multiple variants. Built on Radix UI primitives for full accessibility.

Installation

npm install @nqlib/nqui

Import

import { Checkbox } from '@nqlib/nqui';

Basic Usage

import { Checkbox } from '@nqlib/nqui';

export default function Example() {
  return <Checkbox>Accept terms and conditions</Checkbox>;
}

Examples

'use client';import { Checkbox } from '@nqlib/nqui';export default function Example() {  return (    <div className="flex items-center gap-2">      <Checkbox checked="indeterminate" />      <span className="text-sm">Indeterminate state</span>    </div>  );}

Variants

The Checkbox component supports two variants:

Square Variant (Default)

The square variant features an animated checkmark with a pulse effect and background expansion:

<Checkbox variant="square">Accept terms</Checkbox>

Features:

• Animated checkmark with smooth transitions
• Pulse animation on selection
• Background expansion effect
• Hover state with muted background

Round Variant

The round variant features a circular checkbox with a gooey splash animation:

<Checkbox variant="round" />

Features:

• Circular checkbox design
• Gooey splash animation on selection
• SVG path animation for checkmark
• Smooth transitions

Controlled Checkbox

Use controlled state for programmatic control:

const [checked, setChecked] = useState(false);

<Checkbox checked={checked} onCheckedChange={setChecked}>
  Controlled checkbox
</Checkbox>

Uncontrolled Checkbox

Use defaultChecked for uncontrolled state:

<Checkbox defaultChecked>Subscribe to newsletter</Checkbox>

Disabled State

<Checkbox disabled>Disabled checkbox</Checkbox>

With Label

The square variant includes the label as children. For the round variant, use a separate Label component:

import { Checkbox, Label } from '@nqlib/nqui';

<div className="flex items-center gap-2">
  <Checkbox variant="round" id="terms" />
  <Label htmlFor="terms">Accept terms</Label>
</div>

Props

Enhanced vs Core Checkbox

nqui exports an enhanced Checkbox component by default, which includes:

• Animated variants (square and round)
• Smooth transitions and animations
• Enhanced visual feedback
• Better focus states

For the base Radix Checkbox (without enhancements), you can import CoreCheckbox:

import { CoreCheckbox } from '@nqlib/nqui';

Styling

Checkboxes use CSS variables for theming:

• Primary color: var(--primary)
• Background: var(--card)
• Border: var(--border)
• Foreground: var(--foreground)
• Muted: var(--muted)

Accessibility

• Full keyboard navigation support
• ARIA attributes for screen readers
• Focus management with visible focus rings
• Proper label association
• Disabled state handling

Best Practices

1. Use square variant for forms: The square variant with label text is ideal for form checkboxes
2. Use round variant for toggles: The round variant works well for toggle-like interactions
3. Always provide labels: Ensure every checkbox has an associated label
4. Group related checkboxes: Use FieldSet and FieldLegend for groups
5. Handle disabled states: Clearly indicate when checkboxes are disabled

Next Steps

• Learn about RadioGroup for single selection
• Explore Switch for toggle switches
• Check out Field component for form field wrapper
• See Form Components for other form elements