FormCheckbox

Overview

The FormCheckbox component provides a comprehensive checkbox system that combines labels, descriptions, and validation states. It's designed to create accessible, user-friendly forms that require selection inputs with proper labeling, helpful context, and clear validation feedback while maintaining consistency with the design system.

Usage

import { FormCheckbox } from "@unkey/ui";
 
export default function MyComponent() {
  return (
    <FormCheckbox
      label="I agree to the terms and conditions"
      description="By checking this box, you agree to our terms of service."
      required
    />
  );
}

Examples

Default FormCheckbox

The default FormCheckbox includes a label and optional description text, providing clear context for users.

1
2
3
4

<FormCheckbox
  label="I agree to receive marketing emails"
  description="We'll send you occasional updates about our products"
/>

Required Field

Use the required prop to indicate mandatory fields. This automatically adds a "Required" tag to the label.

1
2
3
4
5

<FormCheckbox
  label="I agree to the Terms of Service"
  description="You must accept our terms to continue"
  required
/>

Required Field with Error

When a required field has an error, the "Required" tag changes to error styling to draw more attention.

1
2
3
4
5

<FormCheckbox
  label="I agree to the Terms of Service"
  required
  error="You must accept the terms to continue"
/>

Optional Field

Use the optional prop to explicitly indicate non-mandatory fields. This adds an "Optional" badge to the label.

1
2
3
4
5

<FormCheckbox
  label="Subscribe to our newsletter"
  description="Get the latest updates directly to your inbox"
  optional
/>

Success State

Indicates successful validation or acceptance of selection. The success icon and text provide positive feedback.

1
2
3
4
5
6
7

<FormCheckbox
  label="Two-factor authentication enabled"
  description="Your account is now more secure"
  variant="primary"
  color="success"
  defaultChecked
/>

Warning State

Used for potentially impactful selections that should be made with caution. Includes a warning icon and explanatory text.

1
2
3
4
5
6

<FormCheckbox
  label="Share usage data with developers"
  description="This includes anonymous activity information"
  variant="primary"
  color="warning"
/>

Error State

Shows validation errors or other issues that need user attention. Features prominent error styling and message.

1
2
3
4
5
6

<FormCheckbox
  label="Delete my account"
  error="This action cannot be undone"
  variant="primary"
  color="danger"
/>

Disabled State

Apply when the field should be non-interactive, such as during form submission or based on other field values.

1
2
3
4
5

<FormCheckbox
  label="Admin privileges"
  description="Only available to authorized personnel"
  disabled
/>

Checked State

Pre-selected checkbox with an initial checked state that users can toggle.

1
2
3
4
5

<FormCheckbox
  label="Remember my preferences"
  description="Save your settings for future visits"
  defaultChecked
/>

Outline Variant

A subtler alternative to the primary variant with transparent background when checked.

1
2
3
4
5

<FormCheckbox
  label="Send me weekly reports"
  description="A summary of your account activity"
  variant="outline"
/>

Ghost Variant

The most minimal styling for checkboxes that need less visual emphasis.

1
2
3
4
5

<FormCheckbox
  label="Show advanced settings"
  description="Display additional configuration options"
  variant="ghost"
/>

Different Sizes

Checkboxes can be sized appropriately for different UI needs.

Small

1
2
3
4
5

<FormCheckbox
  label="I confirm that all information is correct"
  description="Please verify before submission"
  size="sm"
/>

Medium

1
2
3
4
5

<FormCheckbox
  label="I confirm that all information is correct"
  description="Please verify before submission"
  size="md"
/>

Large

1
2
3
4
5

<FormCheckbox
  label="I confirm that all information is correct"
  description="Please verify before submission"
  size="lg"
/>

XLarge

1
2
3
4
5

<FormCheckbox
  label="I confirm that all information is correct"
  description="Please verify before submission"
  size="xlg"
/>

Complex Usage

Example of FormCheckboxes with multiple props configured for a specific use case, such as a cookie consent form.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<div className="space-y-4">
  <FormCheckbox
    label="Accept all cookies"
    description="Enable all cookie types for the best experience"
    variant="primary"
    size="md"
    className="border-b pb-2"
  />
  <div className="pl-6 space-y-2">
    <FormCheckbox
      label="Essential cookies"
      description="Required for the website to function"
      variant="outline"
      size="sm"
      defaultChecked
      disabled
    />
    <FormCheckbox
      label="Performance cookies"
      description="Help us improve site performance and usability"
      variant="outline"
      size="sm"
    />
    <FormCheckbox
      label="Functional cookies"
      description="Enable advanced features and personalization"
      variant="outline"
      size="sm"
    />
    <FormCheckbox
      label="Marketing cookies"
      description="Allow us to provide relevant advertisements"
      variant="outline"
      size="sm"
    />
  </div>
</div>

Features

• Built-in Labeling: Automatic label association with proper accessibility
• Description Support: Optional helper text for additional context
• Validation States: Multiple states (success, warning, error) with appropriate styling
• Required/Optional Indicators: Clear visual indicators for field requirements
• Multiple Variants: Different visual styles (default, outline, ghost) for various contexts
• Size Options: Different sizes for different UI needs
• 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
• Customizable: Extensive styling options through className props

Props

The FormCheckbox component extends the standard Checkbox component props with additional form-specific properties:

Variants

Default

• Standard checkbox with label and optional description
• Use for most checkbox inputs
• Balanced visual weight and accessibility

Required

• Includes "Required" indicator for mandatory fields
• Use for fields that must be completed
• Clear visual indication of importance

Optional

• Includes "Optional" indicator for non-mandatory fields
• Use for fields that can be left empty
• Provides clarity in forms with mixed requirements

Success

• Green styling for positive validation states
• Use for successfully validated selections
• Encourages positive user feedback

Warning

• Yellow/orange styling for cautionary states
• Use for selections that need attention but aren't errors
• Indicates potential issues

Error

• Red styling for validation errors
• Use for failed validation or critical issues
• Clearly indicates problems that need resolution

Outline

• Subtler styling with transparent background when checked
• Use for less prominent selections
• Good for secondary options

Ghost

• Minimal styling for checkboxes that need less visual emphasis
• Use for tertiary or subtle selections
• Perfect for dense UIs

Structure

The FormCheckbox component is composed of:

1. Checkbox Element - The actual checkbox input with validation states
2. Label Container - Contains the label text and required/optional indicators
3. Description Text - Optional helper text below the checkbox
4. Error Message - Validation error display when applicable
5. Status Icons - Visual indicators for different states

Styling

The component includes default styling with:

• Consistent spacing and typography from design system
• Color-coded validation states for semantic meaning
• Proper label positioning and association
• Multiple visual variants for different contexts
• Dark mode support with appropriate color schemes
• Focus states for accessibility
• Customizable through className props

Custom Styling

You can customize the appearance using className props:

<FormCheckbox
  label="Custom Checkbox"
  description="Custom description"
  className="custom-form-checkbox-class"
  variant="outline"
/>

Accessibility

The FormCheckbox component is built with accessibility in mind:

• Label Association: Labels are properly associated with checkboxes using htmlFor/id
• Error Announcements: Error messages are announced to screen readers using role="alert"
• Required Indicators: Required fields are marked both visually and via aria-required
• Helper Text: Helper text is linked to checkboxes using aria-describedby
• Validation States: Error states are indicated using aria-invalid
• Focus Management: Checkboxes maintain proper focus states for keyboard navigation
• Screen Reader Support: Announces validation states and requirements appropriately
• Keyboard Navigation: Full keyboard support for all interactions