Fields

Checkbox Group

Erag\InertiaForms\Fields\CheckboxGroup renders a list of checkboxes and stores the checked option values as an array. When any option has a description, options are drawn as cards. With buttons(), the options become toggle pills.

When to use: picking several values from a short list, where a multi-select would hide the choices.

use Erag\InertiaForms\Fields\CheckboxGroup;

CheckboxGroup::make('topics')->options([
    'news' => 'Product news',
    'tips' => 'Tips and tutorials',
    'events' => 'Events',
])->inline();

Examples

Each example is a live form built from the PHP below it. Fill it in and press submit to see the data your controller would receive.

Basic

Three options on one line. The value is an array of the checked keys.

use Erag\InertiaForms\Fields\CheckboxGroup;

CheckboxGroup::make('topics')
    ->options([
        'news' => 'Product news',
        'tips' => 'Tips and tutorials',
        'events' => 'Events',
    ])
    ->inline();

Cards with descriptions

Options with descriptions become cards; columns(2) puts them in a grid. At least one must be checked.

use Erag\InertiaForms\Fields\CheckboxGroup;

CheckboxGroup::make('channels')
    ->label('Notify me by')
    ->options([
        ['value' => 'email', 'label' => 'Email', 'description' => 'A summary once a day'],
        ['value' => 'sms', 'label' => 'SMS', 'description' => 'Only for urgent alerts'],
        ['value' => 'push', 'label' => 'Push', 'description' => 'On your phone and desktop'],
        ['value' => 'fax', 'label' => 'Fax', 'description' => 'Retired', 'disabled' => true],
    ])
    ->columns(2)
    ->required();

Advanced: toggle pills

buttons() draws each option as a pill. The workdays start with a default selection; the interests are limited to three with rule('max:3'), which is checked on the server.

use Erag\InertiaForms\Fields\CheckboxGroup;

[
    CheckboxGroup::make('workdays')
        ->options([
            'mon' => 'Mon', 'tue' => 'Tue', 'wed' => 'Wed', 'thu' => 'Thu',
            'fri' => 'Fri', 'sat' => 'Sat', 'sun' => 'Sun',
        ])
        ->default(['mon', 'tue', 'wed', 'thu', 'fri'])
        ->buttons()
        ->required(),
    CheckboxGroup::make('interests')
        ->options(['Design', 'Frontend', 'Backend', 'DevOps', 'Testing', 'Security'])
        ->buttons()
        ->rule('max:3')
        ->help('Pick up to three.'),
];

Methods

All common field methods are available, plus:

options(mixed $options)

The choices. Accepts every format described in Combobox → Option formats.

CheckboxGroup::make('permissions')->options(Permission::pluck('label', 'name'));

inline(bool $inline = true)

Place checkboxes next to each other on one line (wrapping when needed).

CheckboxGroup::make('days')->options(['Mon', 'Tue', 'Wed', 'Thu', 'Fri'])->inline();

columns(?int $columns)

Lay options out in a grid of 1 to 4 columns on wider screens. Ignored when inline() is on.

CheckboxGroup::make('features')->options([...])->columns(2);

buttons(bool $buttons = true)

Draw each option as a pill-shaped toggle button. Clicking a pill switches it on (filled with the accent color) or off. Pills wrap onto new lines as needed, which works well for tags, days of the week, or interests. The checkboxes stay in the page (visually hidden), so keyboard and screen reader support is unchanged.

CheckboxGroup::make('days')
    ->options(['mon' => 'Mon', 'tue' => 'Tue', 'wed' => 'Wed', 'thu' => 'Thu', 'fri' => 'Fri'])
    ->buttons();

In this mode only labels are shown; descriptions, inline(), and columns() are ignored.

Validation rules

Key	Rules
name	array (plus required/nullable and your own rules)
name.*	Rule::in(<option values>)

CheckboxGroup::make('topics')->options(['news', 'tips'])->required();
// 'topics'   => ['required', 'array']
// 'topics.*' => [Rule::in(['news', 'tips'])]

required() means at least one box must be checked, because Laravel's required rule rejects an empty array. Use ->rule('min:2') or ->rule('max:3') to limit the count.

Value

• An array of checked option values, in the order they were checked.
• Empty value: [].
• Bound collections and enum lists are converted to a plain array of values.

Standalone use

Vue

<CheckboxGroup v-model="topics" :field="topicsField" id="topics" :disabled="false" />

React

<CheckboxGroup field={topicsField} id="topics" value={topics} disabled={false} onChange={setTopics} />

Svelte

<CheckboxGroup field={topicsField} id="topics" bind:value={topics} disabled={false} />

Like Radio, the group is labelled by an element with the id `${id}-label`. Use FieldWrapper to get the label for free.