CheckboxField

Description

A checkbox field component that supports both single checkbox and multiple checkbox group modes. Integrates with React Hook Form using Controller for better state management.

Import

import { CheckboxField } from '@components/common/form/CheckboxField';

Usage

Single Checkbox

import { Form } from '@components/common/form/Form';
import { CheckboxField } from '@components/common/form/CheckboxField';

function TermsForm() {
  return (
    <Form action="/api/accept">
      <CheckboxField
        name="termsAccepted"
        label="I accept the terms and conditions"
        required
      />
    </Form>
  );
}

Multiple Checkboxes

import { Form } from '@components/common/form/Form';
import { CheckboxField } from '@components/common/form/CheckboxField';

function InterestsForm() {
  const interests = [
    { value: 'tech', label: 'Technology' },
    { value: 'sports', label: 'Sports' },
    { value: 'music', label: 'Music' }
  ];

  return (
    <Form action="/api/interests">
      <CheckboxField
        name="interests"
        label="Select Your Interests"
        options={interests}
      />
    </Form>
  );
}

Props

Name	Type	Default	Description
name	FieldPath<T>	-	Field name (required)
label	string	-	Label text
options	CheckboxOption[]	-	Array of options (if not provided, renders single checkbox)
direction	'horizontal' | 'vertical'	'vertical'	Layout direction for checkbox group
defaultValue	boolean | (string | number)[]	-	Default value (boolean for single, array for multiple)
required	boolean	false	Makes the field required
disabled	boolean	false	Disables all checkboxes
error	string	-	Custom error message
helperText	string	-	Helper text shown in a tooltip
validation	RegisterOptions<T>	-	React Hook Form validation rules
wrapperClassName	string	-	CSS class for the wrapper div
...props	InputHTMLAttributes	-	All standard HTML input attributes

CheckboxOption Type

interface CheckboxOption {
  value: string | number;
  label: string;
  disabled?: boolean;
}

Example: Terms and Conditions

import { Form } from '@components/common/form/Form';
import { CheckboxField } from '@components/common/form/CheckboxField';

function SignupForm() {
  return (
    <Form action="/api/signup">
      <CheckboxField
        name="agreeToTerms"
        label="I agree to the Terms of Service and Privacy Policy"
        required
        validation={{
          validate: (value) => value === true || 'You must accept the terms'
        }}
      />
      
      <CheckboxField
        name="newsletter"
        label="Subscribe to our newsletter"
        defaultValue={true}
      />
    </Form>
  );
}

Example: Feature Selection

import { Form } from '@components/common/form/Form';
import { CheckboxField } from '@components/common/form/CheckboxField';

function FeaturesForm() {
  const features = [
    { value: 'notifications', label: 'Email Notifications' },
    { value: 'analytics', label: 'Analytics Dashboard' },
    { value: 'api', label: 'API Access' },
    { value: 'support', label: 'Priority Support', disabled: true }
  ];

  return (
    <Form action="/api/features">
      <CheckboxField
        name="enabledFeatures"
        label="Enable Features"
        options={features}
        direction="vertical"
        defaultValue={['notifications', 'analytics']}
      />
    </Form>
  );
}

Example: Horizontal Layout

import { Form } from '@components/common/form/Form';
import { CheckboxField } from '@components/common/form/CheckboxField';

function PreferencesForm() {
  const days = [
    { value: 'mon', label: 'Mon' },
    { value: 'tue', label: 'Tue' },
    { value: 'wed', label: 'Wed' },
    { value: 'thu', label: 'Thu' },
    { value: 'fri', label: 'Fri' }
  ];

  return (
    <Form action="/api/preferences">
      <CheckboxField
        name="workingDays"
        label="Select Working Days"
        options={days}
        direction="horizontal"
      />
    </Form>
  );
}

Behavior

Single Checkbox Mode

• When options is not provided or empty
• Returns true or false
• Useful for yes/no, agree/disagree scenarios

Multiple Checkbox Mode

• When options array is provided
• Returns array of selected values
• Allows multiple selections
• Individual options can be disabled

Features

• Dual Mode: Single checkbox or checkbox group
• Horizontal/Vertical Layout: Control layout direction
• Disabled Options: Mark specific options as disabled
• Controller Integration: Uses React Hook Form Controller
• Array Value Management: Automatically handles array of selected values
• TypeScript Support: Full type safety with generics

Related Components

• Form - Parent form component
• RadioGroupField - Single selection with radio buttons
• ToggleField - Switch toggle
• SelectField - Dropdown selection