Checkbox

/**
 * Checkbox Field Demo - Interactive examples of checkbox fields
 */

import { Form, FormBuilder } from '@saastro/forms';

import { FormProvider } from '@/components/FormProvider';
import { TooltipProvider } from '@/components/ui/tooltip';

const config = FormBuilder.create('checkbox-demo')
  .layout('manual')
  .columns(12)
  .addField('newsletter', (f) =>
    f
      .type('checkbox')
      .label('Subscribe to newsletter')
      .helperText('Get weekly updates, tips, and product announcements')
      .optional()
      .columns({ default: 12 }),
  )
  .addField('marketing', (f) =>
    f
      .type('checkbox')
      .label('Receive marketing emails')
      .helperText('Promotional content and special offers')
      .optional()
      .columns({ default: 12 }),
  )
  .addField('terms', (f) =>
    f
      .type('checkbox')
      .label('I agree to the Terms of Service and Privacy Policy')
      .helperText('Required to create an account')
      .required()
      .mustBeTrue('You must accept the terms to continue')
      .columns({ default: 12 }),
  )
  .addField('age', (f) =>
    f
      .type('checkbox')
      .label('I am 18 years or older')
      .required()
      .mustBeTrue('You must be 18 or older')
      .columns({ default: 12 }),
  )
  .addStep('main', ['newsletter', 'marketing', 'terms', 'age'])
  .build();

export default function CheckboxDemo() {
  const handleSubmit = (data: Record<string, unknown>) => {
    console.log('Form submitted:', data);
    alert('Form submitted! Check console for data.');
  };

  return (
    <TooltipProvider>
      <FormProvider>
        <Form config={config} onSubmit={handleSubmit} className="space-y-4" />
      </FormProvider>
    </TooltipProvider>
  );
}

Overview

The checkbox field is a boolean toggle for accepting terms, toggling options, or confirming choices. For multiple checkboxes that share a common label, see Checkbox Group.

Usage

Basic Checkbox

import { FormBuilder } from '@saastro/forms';

const config = FormBuilder.create('signup')
  .addField('newsletter', (f) =>
    f
      .type('checkbox')
      .label('Subscribe to newsletter')
      .helperText('Get weekly updates and tips')
      .optional(),
  )
  .addStep('main', ['newsletter'])
  .build();

Terms Acceptance

Use mustBeTrue() to require the checkbox to be checked:

.addField('terms', (f) =>
  f.type('checkbox')
    .label('I agree to the Terms of Service and Privacy Policy')
    .required()
    .mustBeTrue('You must accept the terms to continue')
)

With Description

.addField('marketing', (f) =>
  f.type('checkbox')
    .label('Marketing emails')
    .helperText('Receive promotional content, product updates, and special offers. You can unsubscribe at any time.')
    .optional()
)

JSON Configuration

{
  "type": "checkbox",
  "label": "I agree to the Terms of Service",
  "schema": {
    "required": true,
    "mustBeTrue": true,
    "mustBeTrueMessage": "You must accept the terms"
  }
}

Props

Validation

Optional (default false)

.addField('newsletter', (f) =>
  f.type('checkbox')
    .label('Subscribe')
    .optional() // Default value is false, but not required
)

Required to be True

.addField('terms', (f) =>
  f.type('checkbox')
    .label('Accept terms')
    .required()
    .mustBeTrue('You must accept the terms')
)

With Zod

import { z } from 'zod';

.addField('terms', (f) =>
  f.type('checkbox')
    .label('Accept terms')
    .schema(z.literal(true, {
      errorMap: () => ({ message: 'You must accept the terms' })
    }))
)

Conditional Logic

Show checkbox based on another field

.addField('premium', (f) =>
  f.type('checkbox')
    .label('Upgrade to Premium')
    .hidden({ field: 'plan', operator: 'equals', value: 'free' })
)

Disable based on condition

.addField('confirm', (f) =>
  f.type('checkbox')
    .label('Confirm changes')
    .disabled((values) => !values.hasChanges)
)

Styling

Custom Classes

.addField('terms', (f) =>
  f.type('checkbox')
    .label('Accept terms')
    .required()
    .mustBeTrue()
    .classNames({
      wrapper: 'bg-muted/30 p-3 rounded-md border',
      input: 'border-primary data-[state=checked]:bg-primary',
      label: 'font-medium',
      error: 'text-destructive text-sm',
    })
)

Responsive Layout

.addField('newsletter', (f) =>
  f.type('checkbox')
    .label('Subscribe to newsletter')
    .optional()
    .columns({ default: 12, md: 6 })
)

JSON Styling

{
  "type": "checkbox",
  "label": "Accept terms",
  "wrapper_className": "bg-muted/30 p-3 rounded-md",
  "label_className": "font-medium",
  "columns": { "default": 12 }
}

Related Fields

• Switch - Toggle switch (more prominent visual)
• Checkbox Group - Multiple related checkboxes
• Button Checkbox - Checkboxes styled as buttons

Accessibility

• Uses Radix UI Checkbox for accessibility
• Supports keyboard activation (Space)
• Proper labeling via label prop
• Focus visible states
• Screen reader announcements for state changes