mad-checkbox-field — Componentes (Admin)

Checkbox booleano único. Integra com MadForm (auto mad:model), MadFormRegistry e MadRenderContext (preenchimento automático via form->fill() / form->set()).

CRITICO: o tema aplica appearance:none em input[type=checkbox]. NUNCA criar um checkbox nativo customizado via CSS — sempre usar este componente (ou as classes .mad-checkbox-wrap + .mad-checkbox + .mad-checkbox-box ao gerar via JS).

Props

Prop	Tipo	Default	Descrição
name	string	''	Nome do campo (obrigatório)
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 secundário abaixo do label
checked	bool	false	Estado inicial (sobreposto pelo `MadRenderContext`)
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	Desabilita input (NÃO posta valor)
readonly	bool	false	Bloqueia interação mas mantém postagem (`pointer-events:none`)
attrs	string	''	Atributos HTML extras (ex: `mad:change="onChange"`)

Estado vem do MadRenderContext — comparação 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="Você concorda com a política de privacidade." required />

Dual-value

Quando a 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`	NÃO	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 />

Ação no servidor (mad:change)

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

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

Dentro de formulário

<mad-form submit="onSave">
    <mad-form-grid :cols="2">
        <mad-input-field name="nome" label="Nome" required />
        <mad-checkbox-field name="ativo" label="Ativo" checked />
    </mad-form-grid>
    <mad-checkbox-field name="aceite" label="Aceito os termos"
        description="Você concorda com a política de privacidade." required />
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form>

Quando usar checkbox vs outras opções

Preciso...	Usar
Booleano simples num form denso (sim/não, marcado)	`<mad-checkbox-field>`
Toggle on/off com visual destacado, preferência com label longa	`<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)	`<mad-dbcheckbox-group-field>`

NUNCA fazer

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

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

{{-- ERRADO: usar checkbox para preferência on/off com label longa --}}
<mad-checkbox-field name="notif" label="Receber notificações por email" />

{{-- CERTO: switch tem visual próprio pra isso --}}
<mad-switch-field name="notif" label="Receber notificações por email" />

{{-- ERRADO: montar checkbox manualmente com div + CSS de toggle --}}
<label class="my-checkbox">
    <input type="checkbox" name="ativo" class="checkbox-input">
    <span class="checkbox-box"></span>
</label>

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

Props#

Uso simples (boolean 1/0)#

Dual-value#

Readonly vs Disabled#

Ação no servidor (mad:change)#

Dentro de formulário#

Quando usar checkbox vs outras opções#

NUNCA fazer#