mad-checkbox-group-field — Componentes (Admin)

Grupo de checkboxes com options manuais (name[]). Integra com MadForm/MadRenderContext — form->fill() pré-marca os selecionados, form->save() persiste.

Quando as options vêm do banco (em vez de um array fixo no Blade/controller), use <mad-dbcheckbox-group-field> — mesma API visual, carregamento automático via model Eloquent e suporte a persistência em pivot.

Props

Prop	Tipo	Default	Descrição
name	string	''	Nome do campo (envia como `name[]`)
label	string	''	Label do grupo
options	array	[]	`['val' => 'Label', ...]`
selected	array\|string	[]	Selecionados (array ou CSV). Auto-resolvido via `MadRenderContext` quando omitido
items	array	—	Alias de `options` (nome gravado pelo editor visual)
layout	string	`'vertical'`	`vertical` ou `horizontal`
as	string	`''`	`button` = variante segmentada (botões em vez de caixinhas)
size	string	`''`	`sm`, `''` (normal), `lg`
break-items	int	`0`	Quebra a linha a cada N itens (só com `layout="horizontal"` e sem `as="button"`)
mode	string	`'comma'`	`comma` (CSV numa coluna) ou `table` (pivot 1:N)
pivot-model	string	`''`	Model da tabela pivot (`mode="table"`)
foreign-key	string	`''`	Coluna FK do registro pai na pivot (`mode="table"`)
item-key	string	`''`	Coluna do item selecionado na pivot (`mode="table"`)
database	string	`MAIN_DATABASE` ou `business`	Conexão usada na pivot
separator	string	`','`	Separador quando `selected` vem como string
width	string	''	Largura inline do wrapper
max-width	string	''	Largura máxima inline do wrapper
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false

Uso básico

@php
    $perms = ['read' => 'Ler', 'write' => 'Escrever', 'delete' => 'Excluir'];
@endphp

<mad-checkbox-group-field name="permissoes" label="Permissões"
    :options="$perms" :selected="['read','write']" layout="horizontal" />

form->save($record) grava $record->permissoes como CSV: 'read,write'.

Layout vertical (padrão)

<mad-checkbox-group-field name="dias" label="Dias da semana"
    :options="['seg' => 'Segunda', 'ter' => 'Terça', 'qua' => 'Quarta']" />

Variante segmentada (`as="button"`)

Troca as caixinhas por botões unidos — útil para filtros e seleção compacta:

<mad-checkbox-group-field name="canais" label="Canais"
    :options="['web' => 'Web', 'app' => 'App', 'loja' => 'Loja']"
    as="button" size="sm" layout="horizontal" />

A classe base mad-checkbox-group permanece no container em todas as variantes (o op reload_checkbox_group e a coleta de valores do MadWire dependem dela) — as/size são apenas modificadores.

Quebra a cada N itens (`break-items`)

<mad-checkbox-group-field name="dias" label="Dias"
    :options="$dias" layout="horizontal" :break-items="4" />

Só tem efeito com layout="horizontal" e sem as="button" (o segmentado é uma peça visual única).

Persistência em pivot (`mode="table"`)

Quando as seleções vivem numa tabela de ligação (1:N) em vez de uma coluna CSV:

<mad-checkbox-group-field name="grupos" label="Grupos"
    :options="$grupos"
    mode="table" pivot-model="IamUserGroup"
    foreign-key="user_id" item-key="group_id" database="iam" />

Com mode="table", os selecionados são carregados sozinhos da pivot no render (quando selected não é informado) e form->save() sincroniza as linhas.

Selected vindo como string (CSV)

Útil quando o valor já vem do banco como string concatenada (em vez de array):

<mad-checkbox-group-field name="tags" label="Tags"
    :options="['promo' => 'Promoção', 'novo' => 'Novidade', 'destaque' => 'Destaque']"
    selected="promo,destaque" separator="," />

Dentro de formulário

<mad-form submit="onSave">
    <mad-input-field name="nome" label="Nome do cargo" required />
    <mad-checkbox-group-field name="permissoes" label="Permissões"
        :options="['read' => 'Ler', 'write' => 'Escrever', 'delete' => 'Excluir']"
        layout="horizontal" required />
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form>

Quando usar checkbox-group vs outras opções

Preciso...	Usar
Booleano simples (sim/não, ativo)	`<mad-checkbox-field>`
Escolher 1 entre N (options fixas)	`<mad-radio-field>`
Escolher N entre N (options manuais, fixas no Blade/controller)	`<mad-checkbox-group-field>`
Escolher N entre N (options do banco, salva CSV ou pivot 1:N)	`<mad-dbcheckbox-group-field>`
N entre N com múltiplas colunas por item (código, nome, status...)	`<mad-checklist-field>`

NUNCA fazer

{{-- ERRADO: checkbox group manual, um <mad-checkbox-field> por opção --}}
@foreach($perms as $k => $l)
    <mad-checkbox-field :name="$k" :label="$l" />
@endforeach

{{-- CERTO: nome único, envia como array --}}
<mad-checkbox-group-field name="permissoes" :options="$perms" />

{{-- ERRADO: carregar options do banco no controller pra passar pro checkbox-group --}}
@php $cats = \App\Models\Categoria::pluck('nome', 'id')->all(); @endphp
<mad-checkbox-group-field name="cats" :options="$cats" />

{{-- CERTO: dbcheckbox-group-field carrega sozinho --}}
<mad-dbcheckbox-group-field name="cats" model="Categoria" display="nome" />

{{-- ERRADO: reimplementar o grupo com JS próprio (querySelectorAll + array manual) --}}
<script>
document.querySelectorAll('.my-group input[type=checkbox]').forEach(cb => {
    cb.addEventListener('change', () => { /* coletar valores manualmente */ });
});
</script>

{{-- CERTO: o componente já gera "name[]" e integra com MadForm/MadRenderContext --}}
<mad-checkbox-group-field name="opcoes" :options="$opts" />

Props#

Uso básico#

Layout vertical (padrão)#

Variante segmentada (as="button")#

Quebra a cada N itens (break-items)#

Persistência em pivot (mode="table")#

Selected vindo como string (CSV)#

Dentro de formulário#

Quando usar checkbox-group vs outras opções#

NUNCA fazer#