Docs›Componentes (Admin)›mad-switch-field
Componentes (Admin)

mad-switch-field

Toggle iOS-style on/off.

Toggle on/off com visual estilo iOS. Integra com MadForm (auto mad:model), MadFormRegistry e MadRenderContext (preenchimento automatico via form->fill() / form->set()).

CRITICO: o tema aplica appearance:none no checkbox interno. NUNCA criar um toggle nativo com <input type="checkbox"> + CSS customizado — sempre usar este componente.

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")
value string '' Valor default do dev (perde para o registro do contexto)
checked bool false Liga por default pela tag (equivale a value = value-on)
width string '' Largura do .mad-field (numero puro = px)
max-width string '' Largura maxima do .mad-field
style string '' Estilo inline no .mad-field

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

Regra de precedencia (Mad\Support\MadFieldValue): registro > checked > value. Sem coluna no contexto, checked e o unico jeito de nascer ligado.

O MadRenderContext tambem controla visibilidade e bloqueio por campo: isHidden($name) adiciona mad-hidden no field e isReadonly($name) liga o readonly mesmo sem a prop.

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

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).

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
}

Dentro de formulario

<mad-form submit="onSave">
    <mad-form-grid :cols="2">
        <mad-input-field name="nome" label="Nome" required />
        <mad-switch-field name="ativo" label="Ativo" variant="success" />
    </mad-form-grid>
    <mad-switch-field name="notif_email" label="Receber notificacoes por email"
        description="Voce sera avisado sobre novidades e promocoes." />
    <mad-btn type="submit" variant="primary" icon="save">Salvar</mad-btn>
</mad-form>

Quando usar switch vs checkbox

Preciso... Usar
Booleano simples num form denso (sim/nao, marcado) <mad-checkbox-field>
Toggle on/off com visual destacado, preferencia com label longa <mad-switch-field>

NUNCA fazer

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

{{-- CERTO --}}
<mad-switch-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: montar toggle manualmente com CSS/JS (slider, knob, etc) --}}
<label class="my-toggle">
    <input type="checkbox" name="ativo" class="toggle-input">
    <span class="toggle-slider"></span>
</label>

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