Checkbox

Checkbox Component

Checkbox fields allow users to select multiple options from a set (checkbox group) or toggle a single binary choice (standalone checkbox). They're ideal for non-exclusive selections and agreement toggles.

Core Properties

interface CheckboxFieldType extends BaseField {
  type: "checkbox";
  options?: Array<string | { value: string | number, label: string | number }>;
  layout?: "inline" | "column"; // Display direction
  itemsClassName?: string;      // CSS classes per checkbox
  itemsStyles?: CSSProperties;  // Inline styles per checkbox
  
  // For single checkbox mode:
  singlePositiveAnswerValue?: string; // Value when checked (default: "true")
  singleNegativeAnswerValue?: string; // Value when unchecked (default: "false")
}

Basic Usage

Checkbox Group

function CheckboxGroupExample() {
  const schema = {
    formId: "checkbox-group",
    fields: [{
      fieldId: "interests",
      type: "checkbox",
      label: "Your Interests",
      options: ["Sports", "Music", "Technology", "Travel"],
      required: true,
      layout: "inline"
    }]
  };
  return <DynamicForm formData={schema} />;
}

Label/Value Pairs

{
  fieldId: "languages",
  type: "checkbox",
  label: "Languages",
  required: true,
  requiredMessage: "An item must be selected",
  options: [
    {
      value: "persian",
      label: "Persian",
    },
    {
      value: "english",
      label: "English",
    },
    {
      value: "germany",
      label: "Germany",
    },
    {
      value: "spanish",
      label: "Spanish",
    },
    {
      value: "arabic",
      label: "Arabic",
    },
    {
      value: "chinese",
      label: "Chinese",
    },
  ],
  _defaultValue: ["persian"]
}

Single Checkbox (Agreement)

{
  fieldId: "acceptTerms",
  type: "checkbox",
  label: "Terms Agreement",
  description: "I accept the terms and conditions",
  required: true,
  singlePositiveAnswerValue: "accepted", // Custom checked value
  singleNegativeAnswerValue: "declined"  // Custom unchecked value
}

Layout Options

Inline Checkbox Group

{
  fieldId: "notifications",
  type: "checkbox",
  layout: "inline",
  options: ["Email", "SMS", "Push"]
}

Column Layout (Default)

{
  fieldId: "skills",
  type: "checkbox",
  layout: "column",
  options: ["JavaScript", "React", "Node.js", "TypeScript"]
}

Styling Examples

CSS class styling

{
  fieldId: "preferences",
  type: "checkbox",
  options: ["Dark Mode", "Notifications", "Newsletter"],
  className: "p-4 border rounded-lg bg-gray-50",
  itemsClassName: "p-2 hover:bg-gray-100 rounded",
  labelClassName: "font-medium text-lg mb-2"
}

Custom Inline Styles

{
  fieldId: "features",
  type: "checkbox",
  options: ["Advanced", "Beta", "Experimental"],
  containerStyles: { 
    backgroundColor: "#f8f9fa",
    padding: "1rem"
  },
  itemsStyles: {
    marginRight: "2rem",
    color: "#333",
    fontSize: "0.9rem"
  }
}

Advanced Features

Dynamic Options

{
  fieldId: "permissions",
  type: "checkbox",
  options: {
    fn: ({ values }) => 
      values.userType === "admin" 
        ? ["Manage Users", "Edit Content", "View Reports"]
        : ["View Content"],
    dependsOn: ["userType"]
  }
}

Validation Examples

{
  fieldId: "selections",
  type: "checkbox",
  options: ["A", "B", "C"],
  validation: [{
    minItems: 2,
    message: "Select at least 2 options"
  }]
}

Conditional Checkbox

{
  fieldId: "parentalConsent",
  type: "checkbox",
  visibility: {
    dependsOn: ["age"],
    fn: ({ values }) => values.age < 21
  },
  description: "Parental consent required for users under 21"
}

Event Handling

Change Tracking

{
  fieldId: "preferences",
  type: "checkbox",
  options: ["Dark Mode", "Notifications"],
  events: {
    onCustomChange: (e) => {
      // write the code you want to run on the field change event
    },
  }
}

Performance Tips

1. Limit Options - Checkbox groups work best with 2-10 options
2. Virtualize Long Lists - For 10+ options, consider a virtualized list
3. Memoize Options - For dynamic options, memoize the array to prevent re-renders