Components

checkbox

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.

When to use

Terms-and-conditions acceptance
Consent declarations and confirmations
Single opt-in / opt-out toggles (a true/false question)

When NOT to use

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

Props

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.

The required mechanism

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.

To make a field required: set defaultRequired: true and pattern: "true".
To make a field optional: set defaultRequired: false.

Examples

{
  "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."
    }
  }
}

Optional opt-in

{
  "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"
  }
}

Checklist

Form Components

Reference index for all IremboHub Formly field components.

customapplicationnumberinput

An input specialised for IremboHub application numbers — validates the format and can look up the referenced application to populate downstream fields.

checkbox

On this page