A single boolean toggle. Use for consent declarations, confirmations, and opt-ins where the user must actively check a box to proceed.
Read Form Rules before using this component — keys, labels, required fields, expressions, visibility, and validation all follow shared conventions.
Instead of checkbox, use… |
For… |
|---|---|
multicheckbox |
Selecting one or more options from a fixed list |
radio |
Picking exactly one option from 2–5 alternatives |
customdropdown |
Choosing one option from a longer list |
| Prop | Type | Required? | Description |
|---|---|---|---|
label |
string |
required | Inline checkbox label. Title Case for nouns, Sentence case for the declaration. Must be unique across the form. |
required |
boolean |
required | Always false. The expression controls the runtime value — never set this to true directly. |
defaultRequired |
boolean |
required | true for required fields, false for optional ones. This is the value the expression reads. |
pattern |
string |
optional | Set to "true" to require the box to actually be checked. Without this, Formly's required validator passes even when the value is false. |
hideLabel |
boolean |
optional | Set to true to suppress the outer label wrapper so the checkbox label is rendered inline only. Required for consent-style checkboxes. |
formCheck |
string |
optional | Layout style. Always "default". |
description |
string |
optional | Secondary helper text below the checkbox. |
tooltip |
string |
optional | Short help text shown as an icon tooltip next to the label. |
indeterminate |
boolean |
optional | Visual indeterminate state. Defaults to false. Optional, but by convention always include it set to false when authoring. |
hideField |
boolean |
optional | Hides the field and excludes its value from submission. Use expressions["props.hideField"] to toggle. Do not use hide directly. |
Every checkbox field must include this exact expression, regardless of whether the field is required or optional. Never omit it, never change it.
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
}
For required consent checkboxes, also set props.pattern: "true" — the required validator alone considers false a valid value, so the user could submit the form without actually checking the box.
defaultRequired: true and pattern: "true".defaultRequired: false.{
"key": "AGREE_TO_TERMS",
"type": "checkbox",
"props": {
"label": "I agree to the terms and conditions",
"required": false,
"defaultRequired": true,
"pattern": "true",
"hideLabel": true,
"indeterminate": false
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
},
"validation": {
"messages": {
"required": "You must accept the terms to proceed."
}
}
}
{
"key": "CONSENT_TO_RECORDS",
"type": "checkbox",
"props": {
"label": "I understand and expressly consent that the information I provide will be recorded in the register.",
"required": false,
"defaultRequired": true,
"pattern": "true",
"formCheck": "default",
"hideLabel": true,
"indeterminate": false
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
},
"validation": {
"messages": {
"required": "You must accept the declaration to proceed."
}
}
}
{
"key": "SUBSCRIBE_TO_UPDATES",
"type": "checkbox",
"props": {
"label": "Send me updates about this service",
"required": false,
"defaultRequired": false,
"hideLabel": true,
"indeterminate": false
},
"expressions": {
"props.required": "!(field?.props?.hideField || field?.hide) && field?.props?.defaultRequired"
}
}
key is UPPER_SNAKE_CASE and unique across the entire formprops.label is present, unique, and correctly casedsections > formly-group > block > checkboxrequired: false is set (never true)defaultRequired is set (true or false)expressions["props.required"] is present with the exact required expressionprops.pattern: "true" is set for any required consent / opt-in checkboxprops.hideLabel: true is set to avoid duplicate label text in the UIprops.indeterminate: false is included (optional, but set by convention)validation.messages.required is present for required checkboxesdefaultValue: true on consent fields — the user must actively opt incheckbox for multi-select lists (see multicheckbox)