Checkbox Group

Multiple checkboxes for selecting one or more options from a visible list with min/max constraints.

Checkbox groups display multiple checkboxes as a vertical list, allowing users to select one or more options. All choices are visible at once, making them ideal for short lists.

Basic Usage

Add a checkbox group using the addCheckboxGroup() builder method:

app/Models/Survey.php

Available Settings

Setting	Type	Description
`options`	array	Key-value pairs for checkbox options
`min_selected`	integer	Minimum number of checkboxes that must be selected
`max_selected`	integer	Maximum number of checkboxes that can be selected
`option_source`	string	Dynamic option source (enum, model or resolver class)

Validation Constraints

Control how many options users can select using minSelected() and maxSelected():

Checkbox groups are validated by the SelectFieldValidator, which ensures:

At least min_selected options are checked (if set)
No more than max_selected options are checked (if set)
All selected values exist in the available options

Dynamic Options

Like select fields, checkbox groups support dynamic options from enums, models or custom resolvers:

Dynamic Option Sources

Checkbox groups use the same option source configuration as select and multi-select fields. Configure enums, models and custom resolvers in config/polyform.php.

Layout

Checkbox groups display options vertically by default:

Each checkbox is displayed on its own line with the label positioned to the right of the checkbox.

Submitted Data Format

Checkbox groups submit their values as a JSON array of selected option keys:

 {
   "features": ["speed", "security", "mobile"]
 }

If no options are selected, the field submits an empty array [].

Frontend Behavior

Click checkbox or label to toggle selection
Tab key navigates between checkboxes
Space bar toggles the focused checkbox
Shows count of selected items when max_selected is set
Disables remaining checkboxes when max_selected is reached
Shows validation errors inline below the group

When to Use

Use Checkbox Group For:

Short lists (2-8 options)
Options that should all be visible
When space is not a constraint
Binary yes/no for multiple items
No search/filter needed

Use Multi-Select For:

Long lists (10+ options)
Space-constrained forms
Search/filter functionality needed
Dynamic loading from database
Mobile-friendly compact display

List Length

Checkbox groups work best with 2-8 options. For longer lists, consider using a Multi-Select field instead to save space and improve usability.

Accessibility

Checkbox groups use fieldset and legend elements for semantic grouping, include ARIA attributes for validation states and support full keyboard navigation. Screen readers announce the group label and the number of options when focused.

Checkbox Radio