Checkboxes field

Use checkboxes when you want respondents to choose several options from a list. You can also let them select an “Other” option and enter text.

Configuration

Name	Type	Required	Default	Description
`type`	string	Yes	—	Set to `checkboxes`.
`name`	string	Yes	—	Submission key. At least 1 character; use letters, digits and underscores, starting with a letter.
`label`	string	No	No question text	Main question text. Supports `{{field}}` piping.
`subtext`	string	No	None	Smaller text under the label. Supports `{{field}}` piping.
`input_label`	string	No	None	Small text above the input. Supports `{{field}}` piping.
`required`	boolean	No	`false`	Set to `true` to require an answer before the respondent leaves the page. A required field shows `*` after its label.
`visible_if`	condition array	No	Always shown	Show the field only when the condition is true. An empty array hides it. See shared properties for condition syntax.
`hide_if`	condition array	No	Never hidden	Hide the field when the condition is true. See shared properties for condition syntax.
`options`	string[]	Yes	—	Choices in the list. Any strings; do not include `"Other"`—use `has_other` instead.
`has_other`	boolean	No	`false`	Set to `true` to add an Other choice with a text input.
`other_label`	string	No	Form language’s word for “Other”	Label for the Other choice. 1–500 characters.
`maxSelections`	integer	No	No limit	Maximum choices one respondent can select, from 1 to 1000. The Other choice counts as one.
`scoring`	number[]	No	Every option scores 0	One number per option, in the same order as `options`.
`capacity`	(integer or null)[]	No	No limit	One entry per option: an integer from 0 to 999,999, or `null` for no limit. Sets the maximum responses each option accepts across submissions.
`randomize`	boolean	No	`false`	Set to `true` to show each respondent the options in a different order.

These fields also follow the shared field property rules. A hidden field is skipped during validation, even if it is required.

Validation respondents see

A required field with nothing selected blocks the page. An empty list or an answer made of only spaces counts as empty.
Selecting Other without entering text blocks the page.
After the respondent reaches maxSelections, remaining options cannot be ticked. An answer over the limit blocks the page and is rejected again at submit.
An option that has reached its capacity cannot be ticked.
When an answer is invalid, the first field with a problem is brought into view and focused, with a message shown under it.

Submission value

The answer is a string array under the field’s name. When the respondent enters text for Other, it is stored as "Other: <text>". For example:

{
  "dietary_needs": ["Vegan", "Other: Nut-free"]
}

Choices on pages the respondent skipped are dropped before the submission is stored. For multi-answer fields, scoring sums the scores for unique selections. defaultValue is ignored for checkboxes.

Example

{
  "type": "checkboxes",
  "name": "dietary_needs",
  "label": "Which dietary options should we provide?",
  "subtext": "Select up to two.",
  "options": ["Vegetarian", "Vegan", "Gluten-free", "Halal"],
  "has_other": true,
  "other_label": "Something else",
  "maxSelections": 2,
  "scoring": [1, 1, 0, 0],
  "capacity": [null, null, 40, 25],
  "randomize": true,
  "required": true
}