Checkbox

A checkbox group component that lets users select multiple options from a predefined list. It renders as a set of checkboxes with individual labels and supports vertical or horizontal layout.

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 option 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).

Tip: Use ‘vertical’ for most use cases – easier to scan, better mobile experience. 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. Optional.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Optional.

Tip: 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.

• 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