mad-dbcheckbox-group-field

Componentes booleanos e de selecao multipla. Todos integram com MadForm (auto mad:model), MadFormRegistry e MadRenderContext (preenchimento automatico via form->fill() / form->set()).

CRITICO: o tema aplica appearance:none em todos input[type=checkbox]. NUNCA criar checkbox/radio nativos — sempre usar estes componentes (ou as classes .mad-checkbox-wrap + .mad-checkbox + .mad-checkbox-box ao gerar via JS).

---

<mad-checkbox-field> — Checkbox unico (booleano)#

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label ao lado do checkbox
value	string	'1'	Valor enviado quando marcado
value-off	string	'0'	Valor postado quando desmarcado
description	string	''	Texto secundario abaixo do label
checked	bool	false	Estado inicial (sobreposto pelo MadRenderContext)
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false	Desabilita input (NAO posta valor)
readonly	bool	false	Bloqueia interacao mas mantem postagem (pointer-events:none)
attrs	string	''	Atributos HTML extras (ex: mad:change="onChange")

Estado vem do MadRenderContext — comparacao feita contra value (suporta dual-value).

Uso simples (boolean 1/0)#

<mad-checkbox-field name="ativo" label="Ativo" />

<mad-checkbox-field name="aceite" label="Aceito os termos"
    description="Voce concorda com a politica de privacidade." required />

Dual-value (valores customizados)#

Quando coluna grava algo diferente de '1'/'0' (ex: 'A'/'I', 'S'/'N'):

<mad-checkbox-field name="status" label="Status do registro"
    value="A" value-off="I" />

<mad-checkbox-field name="confirmado" label="Confirmado"
    value="S" value-off="N" />

form->save($record) persiste exatamente value (marcado) ou value-off (desmarcado).

Readonly vs Disabled#

Prop	Posta valor?	Visual
disabled	NAO	opacity .5, cursor not-allowed
readonly	SIM	opacity .75, pointer-events:none

<mad-checkbox-field name="status" label="Status" value="A" value-off="I" readonly />

---

<mad-radio-field> — Grupo de radio buttons#

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do grupo
options	array	[]	['val' => 'Label'] ou [['value','label','disabled','description']]
selected	string	auto	Valor selecionado (auto via MadRenderContext quando omitido)
inline	bool	false	Layout horizontal
break-items	int	0	Quebra linha a cada N items (so com inline, nao se aplica em as=button)
as	string	''	'' (radio circular padrao) ou button (segmented btn-group)
boolean	bool	false	Atalho Sim/Nao — gera options 1=Sim, 2=Nao, ativa as=button + inline
size	string	''	'' (normal), sm, lg
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras (mad:change="...", etc)
style	string	''	Estilo inline no wrapper

Estado vem automaticamente do MadRenderContext (form->fill($record) pre-seleciona).

Uso basico#

@php $tipos = ['F' => 'Pessoa Fisica', 'J' => 'Pessoa Juridica']; @endphp

<mad-radio-field name="tipo" label="Tipo" :options="$tipos" inline required />

Variante button (segmented btn-group)#

Visual mais compacto, ideal para toggles de status/modo:

<mad-radio-field name="periodo" label="Periodo" as="button"
    :options="['dia' => 'Dia', 'sem' => 'Semana', 'mes' => 'Mes', 'ano' => 'Ano']" />

Modo boolean (atalho Sim/Nao)#

<mad-radio-field name="ativo" label="Ativo" boolean />
{{-- Equivale a: as=button, inline=true, options=['1' => 'Sim', '2' => 'Nao'] --}}

Tamanhos#

<mad-radio-field name="x" :options="$opts" size="sm" />
<mad-radio-field name="x" :options="$opts" size="lg" as="button" />

Quebra a cada N items (inline)#

<mad-radio-field name="cor" :options="$cores" inline :break-items="4" />
{{-- 4 items por linha --}}

Com descricao por opcao#

@php
    $planos = [
        ['value' => 'basic', 'label' => 'Basico', 'description' => 'Ate 5 usuarios'],
        ['value' => 'pro',   'label' => 'Pro',    'description' => 'Usuarios ilimitados'],
        ['value' => 'ent',   'label' => 'Enterprise', 'description' => 'SLA dedicado', 'disabled' => true],
    ];
@endphp
<mad-radio-field name="plano" label="Plano" :options="$planos" />

Com mad:change (acao no servidor)#

<mad-radio-field name="tipo" :options="$tipos" inline
    attrs='mad:change="onTipoChange"' />

Reload remoto via PHP#

$this->form->setItems('tipo', ['F' => 'Fisica', 'J' => 'Juridica'], 'F');
// Gera op reload_radio — preserva variant button automaticamente

---

<mad-switch-field> — Toggle on/off#

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label principal
description	string	''	Texto secundario (vira card quando presente)
value-on	string	'1'	Valor enviado quando ligado
value-off	string	'0'	Valor enviado quando desligado
variant	string	''	Cor do track ligado: primary, success (default), warning, danger, info
size	string	''	Tamanho: sm, '' (normal), lg
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false	Desabilita o input (NAO posta valor)
readonly	bool	false	Bloqueia interacao mas mantem postagem (pointer-events:none)
attrs	string	''	Atributos HTML extras (ex: mad:change="onChange")

Estado vem automaticamente do MadRenderContext — comparacao e feita contra value-on (suporta dual-value como 'A'/'I').

Uso simples (boolean 1/0)#

<mad-switch-field name="ativo" label="Ativo" />

<mad-switch-field name="notif_email" label="Receber notificacoes por email"
    description="Voce sera avisado sobre novidades e promocoes." />

Dual-value (valores customizados)#

Quando o banco grava algo diferente de '1'/'0' (ex: 'A'/'I', 'S'/'N'):

<mad-switch-field name="status" label="Status"
    value-on="A" value-off="I" />

<mad-switch-field name="autoriza" label="Autorizado"
    value-on="S" value-off="N" />

form->save($record) persiste exatamente o valor declarado em value-on ou value-off — sem coercao para '1'/'0'.

Variant de cor#

<mad-switch-field name="ativo" label="Ativo" variant="primary" />
<mad-switch-field name="alerta" label="Alerta" variant="warning" />
<mad-switch-field name="bloqueado" label="Bloqueado" variant="danger" />

Default e success (verde). Use variant pra adequar a cor ao contexto (ex: danger para "bloqueado").

Tamanhos#

<mad-switch-field name="x" label="Pequeno" size="sm" />
<mad-switch-field name="y" label="Normal" />
<mad-switch-field name="z" label="Grande" size="lg" />

Readonly vs Disabled#

Prop	Posta valor?	Visual
disabled	NAO	opacity .5, cursor not-allowed
readonly	SIM	opacity .75, pointer-events:none

{{-- Visual normal mas bloqueado para o usuario; valor ainda e persistido --}}
<mad-switch-field name="status" label="Status" readonly />

Acao no servidor (mad:change)#

<mad-switch-field name="ativo" label="Ativo"
    attrs='mad:change="onAtivoChange"' />

public function onAtivoChange(string $value): void
{
    // $value = valueOn ou valueOff conforme registrado
}

Diferenca para mad-checkbox-field: visual de toggle iOS, ideal para preferencias on/off com label longa.

---

<mad-checkbox-group-field> — Grupo de checkboxes (options manuais)#

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (envia como name[])
label	string	''	Label do grupo
options	array	[]	['val' => 'Label', ...]
selected	array/string	[]	Selecionados (array ou CSV)
layout	string	'vertical'	vertical ou horizontal
separator	string	','	Separador quando selected vem como string
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false

Uso#

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

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

---

<mad-dbcheckbox-group-field> — Grupo de checkboxes via model Eloquent#

Carrega options direto do banco (mesma logica do dbcombo-field) e suporta persistencia automatica em pivot via form->save().

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo
label	string	''	Label do grupo
model	string	''	Classe do model Eloquent fonte das options
database	string	MAIN_DATABASE	Conexao
key	string	'id'	Campo PK
display	string	'nome'	Campo de exibicao. Aceita template {nome} ({sigla})
order-by	string	display	Ordenacao
query	Builder	null	Eloquent/Query Builder pronto (alternativa a model+filters)
filters	array	[]	[['campo','op','val'], ...]
order	string	'asc'	Direcao do order-by: asc ou desc
selected	array/string	auto	Selecionados (auto-load no modo table)
layout	string	'vertical'	vertical ou horizontal
as	string	''	'' (caixas padrao) ou button (pilulas segmentadas)
size	string	''	'' (normal), sm ou lg
break-items	int	0	Quebra linha a cada N itens — so vale com layout="horizontal" e as=""
width / max-width	string	''	Largura / largura maxima do campo (qualquer unidade CSS)
separator	string	','	Separador para CSV
mode	string	'comma'	comma (CSV numa coluna) ou table (pivot 1:N)
pivot-model	string	''	Classe Eloquent da pivot (mode=table)
foreign-key	string	''	Coluna FK do registro pai (mode=table)
item-key	string	''	Coluna FK do item selecionado (mode=table)
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false

Modo comma — CSV numa coluna#

<mad-dbcheckbox-group-field name="categorias_csv" label="Categorias"
    model="Categoria" display="nome" order-by="nome" layout="horizontal" />

form->save($record) salva $record->categorias_csv = '1,3,7'.

Modo table — pivot 1:N#

<mad-dbcheckbox-group-field name="grupos" label="Grupos do usuario"
    model="SystemGroup" database="permission" display="name"
    mode="table" pivot-model="SystemUserGroup"
    foreign-key="system_user_id" item-key="system_group_id" />

form->save($user) apaga todos SystemUserGroup com system_user_id = $user->id e re-insere um por checkbox marcado. O selected carrega automaticamente da pivot no onEdit.

Com filtro#

<mad-dbcheckbox-group-field name="tags" label="Tags"
    model="Tag" display="nome"
    :filters="[['ativo', '=', '1']]" />

---

<mad-dbradio-field> — Grupo de radio buttons via model Eloquent#

Mesma logica do dbcombo-field (auto-load de options do banco) com a renderizacao do radio-field. Usar quando as opcoes vem de uma tabela e o usuario escolhe 1 entre N.

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio)
label	string	''	Label do grupo
model	string	''	Classe do model Eloquent fonte das options
database	string	MAIN_DATABASE	Conexao
key	string	'id'	Campo PK
display	string	'nome'	Campo de exibicao. Aceita template {nome} ({sigla})
order-by	string	display	Ordenacao
query	Builder	null	Eloquent/Query Builder pronto (alternativa a model+filters; incompativel com depends-on)
filters	array	[]	[['campo','op','val'], ...]
selected	string	auto	Valor pre-selecionado
inline	bool	false	Layout horizontal
depends-on	string	''	Nome do campo pai para cascata automatica
depends-column	string	depends-on	Coluna do model filho a filtrar (se diferente do campo pai)
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false
attrs	string	''	Atributos HTML extras

Uso basico#

<mad-dbradio-field name="tipo_produto_id" label="Tipo"
    model="TipoProduto" display="descricao" inline />

Com filtros#

<mad-dbradio-field name="status_id" label="Status"
    model="Status" display="nome" order-by="ordem"
    :filters="[['ativo', '=', '1']]" />

Com depends-on (cascata automatica)#

Ao selecionar o campo pai, o radio filho recarrega automaticamente filtrando pelo valor selecionado — sem AJAX manual.

<mad-dbcombo-field name="familia_produto_id" label="Familia"
    model="FamiliaProduto" display="nome" />

<mad-dbradio-field name="tipo_produto_id" label="Tipo"
    model="TipoProduto" display="descricao"
    depends-on="familia_produto_id" inline />

Se a coluna do model filho tiver nome diferente do campo pai, usar depends-column:

<mad-dbradio-field name="cidade_id" label="Cidade"
    model="Cidade" display="nome"
    depends-on="estado_id" depends-column="estado_id" />

NUNCA fazer#

{{-- ERRADO: carregar options do banco no controller pra passar pro radio-field --}}
@php $tipos = TipoProduto::getIndexedArray('id', 'descricao'); @endphp
<mad-radio-field name="tipo_id" :options="$tipos" />

{{-- CERTO: dbradio-field carrega sozinho --}}
<mad-dbradio-field name="tipo_id" model="TipoProduto" display="descricao" />

{{-- ERRADO: montar cascata manualmente via mad:change + MadResponse --}}
<mad-dbcombo-field name="familia_id" mad:change="onFamiliaChange" />
<mad-radio-field name="tipo_id" :options="$tipos" />

{{-- CERTO: depends-on faz a cascata automaticamente --}}
<mad-dbradio-field name="tipo_id" model="TipoProduto" display="descricao"
    depends-on="familia_id" />

---

Resumo de decisao#

Preciso...	Usar
Booleano simples (sim/nao, ativo, marcado)	<mad-checkbox-field>
Toggle on/off com visual destacado	<mad-switch-field>
Escolher 1 entre N (options fixas)	<mad-radio-field>
Escolher N entre N (options manuais)	<mad-checkbox-group-field>
Escolher N entre N (options do banco, salva CSV)	<mad-dbcheckbox-group-field mode="comma">
Escolher N entre N (options do banco, salva em pivot 1:N)	<mad-dbcheckbox-group-field mode="table">

---

NUNCA fazer#

{{-- ERRADO: input nativo — fica invisivel pelo CSS do tema --}}
<input type="checkbox" name="ativo" value="1">

{{-- CERTO --}}
<mad-checkbox-field name="ativo" label="Ativo" />

{{-- ERRADO: usar checkbox para preferencia on/off com label longa --}}
<mad-checkbox-field name="notif" label="Receber notificacoes por email" />

{{-- CERTO: switch tem visual proprio pra isso --}}
<mad-switch-field name="notif" label="Receber notificacoes por email" />

{{-- ERRADO: gerar radio buttons com @foreach manual --}}
@foreach($tipos as $v => $l)
    <label><input type="radio" name="tipo" value="{{ $v }}"> {{ $l }}</label>
@endforeach

{{-- CERTO --}}
<mad-radio-field name="tipo" :options="$tipos" />

{{-- ERRADO: checkbox group manual --}}
@foreach($perms as $k => $l)
    <mad-checkbox-field :name="$k" :label="$l" />
@endforeach

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

{{-- ERRADO: carregar options do banco no controller pra passar pro checkbox-group --}}
$cats = Categoria::getIndexedArray('id', 'nome');
<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: salvar pivot manualmente quando dbcheckbox-group resolve --}}
foreach ($_POST['grupos'] as $gid) {
    $ug = new SystemUserGroup();
    $ug->system_user_id = $user->id;
    $ug->system_group_id = $gid;
    $ug->save();
}

{{-- CERTO: mode=table + form->save() --}}
<mad-dbcheckbox-group-field name="grupos" model="SystemGroup"
    mode="table" pivot-model="SystemUserGroup"
    foreign-key="system_user_id" item-key="system_group_id" />

{{-- ERRADO: implementar checkbox/radio/switch group do zero com inputs nativos + JS custom --}}
<div class="my-checkbox-group">...</div>
<script>/* logica manual de marcar/desmarcar */</script>

{{-- CERTO --}}
<mad-checkbox-group-field name="opcoes" :options="$opts" />