Checkbox

A checkbox group component that lets users select multiple options from a predefined list. It renders a set of checkboxes with individual labels and can be arranged vertically or horizontally.

Use Cases

• Multi‑select options such as interests, skills, or preferences
• Feature selection like amenities, services, or add‑ons
• Permission checkboxes for roles or access levels
• Agreement checkboxes for terms, privacy, or marketing consent
• Data‑bound multi‑select fields

Properties

name

Unique field name for the checkbox group. Type: string. Required.

label

Group label displayed above checkboxes. Type: string. Optional.

options

Array of checkbox options to display. Type: array. Required. Minimum items: 1. Each item is an object with the following properties:

• value – Internal value stored when the checkbox is checked. Type: string. Required.
• label – Display text shown next to the checkbox. Type: string. Required.

layout

Layout direction for checkbox options. Type: string. Optional. Options: vertical, horizontal. Default: vertical. Visual Impact: vertical – checkboxes stacked vertically (default, recommended for most use cases); horizontal – checkboxes arranged horizontally in a row (only use for 2‑3 short options). Recommendations: default – Use ‘vertical’ for most use cases – easier to scan, better mobile experience; horizontal – Use ‘horizontal’ only for 2‑3 short options that fit on one line.

required

Whether at least one checkbox must be checked to submit the form. Type: boolean. Optional. Default: false.

checkedByDefault

Array of option values that should be checked by default (not used when dataBinding is set). Type: array of strings. Optional.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Optional. Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi‑tenant isolation enforced).

dataBinding

Data binding configuration to connect the checkbox group to a page data source field. Automatically populates checked state and saves changes back to the source. Type: object. Optional.

Sub‑properties:

• pageDataSourceRef – Reference to page‑level data source (format: ‘@page.{dataSourceId}’). Takes precedence over sourceId/sourceType. Type: string. Optional.
• sourceId – ID of the data source (database table or API connection). Type: string. Required.
• sourceType – Type of data source. Type: string. Required. Options: table, api.
• operationType – Operation type – ‘Get’ for single record (input fields use Get). Type: string. Required. Options: Get.
• fieldName – Name of the field/column to bind to (should be array or comma‑separated string field). Type: string. Required.
• isReadOnly – Whether the checkbox group is read‑only (display only, no write back). Type: boolean. Optional. Default: false.
• writeOperation – Write operation type when saving changes. Type: string. Optional. Options: Create, Update. Default: Update.

Best Practices

• CRITICAL: Checkbox groups must be FULL WIDTH – never place in multi‑column Grid/Flex layouts
• Use layout: ‘vertical’ for most use cases (easier to scan, better mobile experience)
• Use layout: ‘horizontal’ only for 2‑3 short options
• Provide clear option labels that describe each choice
• Set required: true when at least one selection is mandatory
• Use Checkbox for multi‑select – use Radio for single‑choice selections
• Use Dropdown if you have 10+ options (checkbox groups work best with 2‑8 options)

Common Mistakes

Placing checkbox groups in multi-column Grid/Flex layouts

Why it's a problem: Labels get truncated, checkboxes hard to scan, looks cramped, poor mobile experience

Fix: NEVER put checkbox groups in Grid/Flex with other fields. Place at full width separately.

Using layout: ‘horizontal’ for many options or long labels

Why it's a problem: Horizontal layout with 4+ options or long labels wraps awkwardly and is hard to scan

Fix: Use layout: ‘vertical’ (default) for most use cases. Only use ‘horizontal’ for 2‑3 short options.

Too many options (10+ ) in checkbox group

Why it's a problem: Large checkbox groups are overwhelming and hard to scan

Fix: Use Dropdown for 10+ options. Checkbox groups work best with 2‑8 options.

Using Checkbox when Radio would be more appropriate

Why it's a problem: Checkbox allows multiple selections – if user should pick only ONE option, use Radio instead

Fix: Use Checkbox for multi‑select, Radio for single‑choice selections

Omitting the options array for a single boolean toggle (e.g., ‘Play vs Computer’)

Why it's a problem: Checkbox ALWAYS requires an options array with at least one item. Without options, no <input> elements render and scripts cannot find the checkbox in the DOM.

Fix: For a single toggle, provide exactly one option: options: [{ label: ‘Yes’, value: ‘yes’ }]. Example: { name: ‘vs_computer’, label: ‘Play vs Computer’, options: [{ label: ‘Yes’, value: ‘yes’ }] }