Introduction

The Checkbox component is a form control that allows users to toggle between binary choices (checked or unchecked) and indeterminate states. Fully optimized for the page builder, the component supports standard browser behaviors and can be customized with state conditions (such as invalid and disabled states) and accented design themes.

Usage

You can customise and structure checkboxes as following for example:

Basic Checkbox

A standard checkbox with an interactive click label for straightforward user options.

{
  "blockType": "checkbox",
  "label": "Accept Terms and Conditions"
}

Pre-Checked Checkbox

Configure a checkbox to render in the checked state by default when the page first loads.

{
  "blockType": "checkbox",
  "label": "Subscribe to our newsletter",
  "checked": true
}

Disabled Checkbox

Prevent users from interacting with the checkbox while preserving its current visual state.

{
  "blockType": "checkbox",
  "label": "Auto-renew subscription (fixed)",
  "checked": true,
  "disabled": true
}

Invalid Validation State

Indicate that a checkbox field has failed validation. For example, forcing a check to accept mandatory policy terms. The input is highlighted with error boundaries using the design system's default status tokens.

{
  "blockType": "checkbox",
  "label": "I accept the User Policy Agreement",
  "invalid": true
}

Accent-Themed Checkbox

Tint checked states and focus markers with custom aesthetic accents from the design system's color palette, and scale sizes up or down.

{
  "blockType": "checkbox",
  "label": "Purple Large Checkbox",
  "checked": true,
  "size": "lg",
  "colorPalette": "purple"
}

Props

Architecture Notes

• Uncontrolled Default Checks: To prevent checkboxes from locking up (preventing user clicks) in static, data-driven templates without custom inline handlers, the CMS field checked resolves as defaultChecked in our page registry.
• Form Standard Reset: The component integrates with standard HTML form resets. Resets seamlessly return the checkboxes back to their original checked states configured in the JSON template.
• Native Keyboard Focus: Focus indicators and toggle interactions (spacebar key triggers) rely on standard HTML inputs and browser behavior. This remains highly performant and accessible on assistive screen-readers.