# `checkboxes`

A checkboxes field allows a list of options where a user can select one or more items. Checkbox items can also be deselected, unlike radio fields.

# Module field definition

// Configuring the `genres` field in a module's `fields.add` subsection:
genres: {
  label: 'Select the genres that apply to this book',
  type: 'checkboxes',
  choices: [
    {
      label: 'Romance 🥰',
      value: 'romance'
    },
    {
      label: 'Comedy 🤣',
      value: 'comedy'
    },
    {
      label: 'Crime 😰',
      value: 'crime'
    }
  ]
}

# Settings

# Required

Property	Type	Default	Description
`choices`	`array`	n/a	An array of options that the editor can select from, or a method name that returns them. See below.
`label`	String	n/a	Sets the visible label for the field in the UI
`type`	String	n/a	Specifies the field type (`checkboxes` for this type)

# Optional

Property	Type	Default	Description
`def`	Array	n/a	The default value for the field. Values must be from the defined choices' values.
`help`	String	n/a	Help text for the content editor
`htmlHelp`	String	n/a	Help text with support for HTML markup
`if`	Object	`{}`	Conditions to meet before the field is active. See the guide for details.
`required`	Boolean	`false`	If `true`, the field is mandatory
`readOnly`	Boolean	`false`	If `true`, prevents the user from editing the field value
`style`	String	n/a	If 'combo', adds a selection choices box and dropdown list of choices
`all`	Object	n/a	If `style: 'combo'`, adds a choice to select every option with a label set by the `label` property

# `choices` configuration

The choices setting in checkboxes, radio, or select fields configures the options that a user will see in the interface and the values that the server will allow in validation. The choices value is an array of objects with label and value properties.

value is used in the field's database value
label is the more human-readable version used in interfaces

# Populating `choices` dynamically

What if the choices aren't known in advance? Then you can fetch them dynamically.

First, set the choices option to the name of a method in your module. Pass a string, the name of the method you'll implement on the server side — do not pass a function.

Second, implement that method in your module so that it takes (req, data) arguments and return an array of choices in the usual format. You may use an async function, or return a promise that will resolve to the array. That means you can reach out to APIs using modules like axios or node-fetch, or make Apostrophe database queries.

The data argument is an object containing the parent's docId for further inspection by your function.

It is usually a good idea to perform at least short-term caching in your choices method, in order to limit the impact on performance when editing.

# Use in templates

The checkboxes field data value is stored in an array of the selected options' value. Nunjucks provides the {% for %} template tag (opens new window) that you can use to loop over the array.

<ul>
  {% for genre in data.piece.genres %}
    <li>{{ genre }}</li>
  {% endfor %}
</ul>

← boolean color →

# checkboxes