Checkbox
The checkbox type renders a single boolean toggle. It stores true when checked and false when unchecked. Use it for agreement confirmations, feature flags, opt-in fields, and any binary yes/no question. It also supports an indeterminate state for tri-state scenarios.
Minimal Example
{
"id": "agree-terms",
"type": "checkbox",
"label": "I agree to the Terms and Conditions",
"required": true,
"width": "full",
"binding": {
"source": "$json",
"path": "registration.agreedToTerms"
}
}Settings Reference
| Setting | Type | Default | Description |
|---|---|---|---|
checkedLabel | string | — | Text shown beside the checkbox when checked |
uncheckedLabel | string | — | Text shown beside the checkbox when unchecked |
indeterminate | boolean | false | Programmatically set the indeterminate (dash) state |
size | sm | md | lg | md | Checkbox size variant |
labelPosition | right | left | right | Position of the label relative to the checkbox |
checkedValue | any | true | Value stored when checked (e.g., "yes", 1) |
uncheckedValue | any | false | Value stored when unchecked (e.g., "no", 0) |
Required Checkbox Validation
For terms-of-service or consent fields where the user must check the box to proceed, set required: true. The validation fails if the stored value is false or null:
{
"id": "marketing-consent",
"type": "checkbox",
"label": "I consent to receive marketing communications",
"required": false,
"defaultValue": false,
"binding": {
"source": "$json",
"path": "preferences.marketingConsent"
}
},
{
"id": "terms-accepted",
"type": "checkbox",
"label": "I have read and accept the Terms of Service",
"required": true,
"validation": {
"required": true,
"message": "You must accept the Terms of Service to continue"
}
}Custom Checked / Unchecked Values
If your data model uses non-boolean values (e.g., "Y"/"N" for legacy systems), configure custom stored values:
{
"id": "active-flag",
"type": "checkbox",
"label": "Active",
"settings": {
"checkedValue": "Y",
"uncheckedValue": "N"
},
"binding": {
"source": "$json",
"path": "record.activeFlag"
}
}
// Stored: "Y" when checked, "N" when uncheckedDynamic Label Based on State
Use checkedLabel and uncheckedLabel to change the displayed text based on the current state:
{
"id": "notifications-enabled",
"type": "checkbox",
"label": "Email Notifications",
"settings": {
"checkedLabel": "Enabled — you will receive email updates",
"uncheckedLabel": "Disabled — no email updates will be sent"
},
"defaultValue": true,
"binding": {
"source": "$json",
"path": "preferences.emailNotifications"
}
}Indeterminate State
The indeterminate state (dash/minus icon) is used in select-all patterns where some but not all sub-items are checked. It is a display-only state — clicking toggles to checked:
// In your action handler or reactive expression:
// Set indeterminate via formEngine.setFieldValue('select-all', null)
// The checkbox reads null as indeterminate
{
"id": "select-all",
"type": "checkbox",
"label": "Select All",
"settings": {
"indeterminate": true // initial state if some are pre-selected
}
}Checkbox vs Switch vs Radio
| Control | Use When |
|---|---|
checkbox | Single boolean field; agreement or opt-in; part of a multi-check list |
switch | Immediate-effect toggle (enable/disable feature); settings panels |
radio | Mutually exclusive selection from 2–6 visible options |
Action gating with disabledRule
A common pattern is disabling the Submit button until a required checkbox is checked. Use disabledRule on the action:
{
"id": "submit",
"type": "submit",
"label": "Create Account",
"disabledRule": "!values['terms-accepted']"
}