mad-select-check-field

Multi-select com checkboxes no dropdown e display condensado no control (Item1, Item2, Item3 +4 itens).

Visual esperado#

Estado	Aparencia
Dropdown aberto	Cada option renderizada como checkbox (modo check do widget MAD Select, ativado via data-mad-selectcheck). Usuario marca/desmarca multiplos.
Control fechado	Uma linha compacta: Item1, Item2, Item3 +4 itens

Diferente do <mad-multi-search-field> que mostra chips individuais com botao remove.

Diferenca entre as duas variantes#

	<mad-select-check-field>	<mad-dbselect-check-field>
Origem das options	:options array PHP	Auto-query Eloquent (render-time)
Quando usar	Enum, lista hardcoded	Lista do banco (pequena/media)

Para listas grandes com busca AJAX, usar <mad-dbmulti-search-field>.

---

<mad-select-check-field> — Options manuais#

Props#

Prop	Tipo	Default	Descricao
name	string	''	Nome do campo (obrigatorio, envia como name[])
label	string	''	Label do campo
options	array	[]	Mapa [valor => label]
selected	array/string	[]	IDs pre-selecionados (aceita array ou CSV)
max-display	int	3	Itens visiveis no control antes do +X itens
placeholder	string	'Selecione...'	Placeholder
max-size	int	0	Maximo de selecoes (0 = ilimitado)
mode	string	'comma'	comma ou table
pivot-model	string	''	Model Eloquent da pivot (mode=table)
foreign-key	string	''	FK do pai (mode=table)
item-key	string	''	FK do item (mode=table)
database	string	MAIN_DATABASE	Conexao da pivot
hint	string	''	Texto de ajuda
error	string	''	Mensagem de erro
required	bool	false
disabled	bool	false
attrs	string	''	Attrs extras
id	string	auto	ID do <select> (default gerado: mad_<name>_<random>)

Uso basico#

@php
    $frutas = ['maca' => 'Maçã', 'banana' => 'Banana', 'uva' => 'Uva', 'manga' => 'Manga'];
@endphp
<mad-select-check-field name="frutas" label="Frutas favoritas" :options="$frutas" />

Com max-display customizado#

<mad-select-check-field name="permissoes" label="Permissoes"
    :options="$permissoes" max-display="2"
    :selected="['read', 'write', 'delete']" />

{{-- Aparece: "Ler, Escrever +1 item" --}}

Com limite de selecoes#

<mad-select-check-field name="tags" label="Ate 5 tags"
    :options="$tagOptions" max-size="5" />

---

<mad-dbselect-check-field> — Auto-query do banco#

Props DB (alem das props do select-check)#

Prop	Tipo	Default	Descricao
model	string	''	Classe do model Eloquent (obrigatorio)
database	string	MAIN_DATABASE	Conexao
key	string	'id'	Campo PK
display	string	'nome'	Campo de exibicao. Aceita template {nome} ({sigla})
order-by	string	''	Ordenacao SQL
query	Builder	null	Eloquent/Query Builder pronto (prioridade sobre model)
filters	array	[]	Atalho [['campo','op','val'], ...] — vira query internamente

Uso basico#

<mad-dbselect-check-field name="categorias" label="Categorias"
    model="Categoria" display="nome" order-by="nome" />

Com filtros e template#

<mad-dbselect-check-field name="tipos" label="Tipos ativos"
    model="TipoProduto" display="{nome} (#{id})"
    :filters="[['ativo', '=', 'T']]" order-by="nome" />

Com query Eloquent (filtro avancado)#

Para condicoes que filters nao cobre (joins, orWhere, escopos do model), passe um Builder pronto via :query — ele tem prioridade sobre model:

<mad-dbselect-check-field name="categorias" label="Categorias"
    :query="Categoria::query()->where('ativo', true)->orderBy('nome')"
    display="nome" />

Mode table (pivot 1:N)#

Persistencia automatica via form->save($parent) — mesmo padrao do <mad-multi-search-field mode="table">.

<mad-dbselect-check-field name="categorias" label="Categorias do produto"
    model="Categoria" display="nome"
    mode="table"
    pivot-model="ProdutoCategoria"
    foreign-key="produto_id"
    item-key="categoria_id" />

public function onSave(): MadResponse
{
    $produto = Produto::findOrNew($this->registroId);
    $this->form->save($produto); // cuida das categorias automaticamente
    return MadToast::success('Salvo!');
}

---

Comparacao com outros multi-selects#

Cenario	Componente
Chips visuais (poucos itens, remove individual)	<mad-multi-search-field>
Linha compacta "+X itens" (options em memoria)	<mad-select-check-field>
Linha compacta "+X itens" (do banco)	<mad-dbselect-check-field>
Checkboxes verticais em lista	<mad-checkbox-group-field> / <mad-dbcheckbox-group-field>
Lista grande (200+) com busca AJAX	<mad-dbmulti-search-field>
Busca com modal grid + paginacao	<mad-seek> (multi)

---

Arquitetura#

• Widget proprietario MAD Select (componente Alpine.js madSelect(), definido em mad-ui.js) em modo check — ativado pelo atributo data-mad-selectcheck no <select multiple> nativo (classes mad-input mad-bsc no select original)
• O <select> nativo continua sendo a unica fonte de verdade (options/selected); o Alpine so projeta a UI por cima dele (_madCreateSelect move o select pra dentro de um wrapper .mad-sel e monta o control/dropdown)
• No modo check, cada <option> vira um <li class="mad-sel-option"> com <input type="checkbox" class="mad-sel-checkbox"> dentro do dropdown
• Control fechado mostra summaryText(): junta os primeiros max-display items com , e acrescenta +X item(s) quando sobram mais selecionados que o limite
• Marcar uma option no modo check nao fecha o dropdown (só o modo single fecha após selecionar) — permite marcar varias seguidas
• Items ja selecionados continuam visiveis no dropdown no modo check (o filtro que some com os ja selecionados em outros modos multi não se aplica ao check)
• Registra como 'multi-search' no MadFormRegistry → compartilha persistencia mode comma/table com o multi-search-field

JS#

Inicializacao via _madInitSelectCheck(root) (definida em assets/builder-ui/mad-ui.js, que delega pra _madCreateSelect). Chamada em:

• DOMContentLoaded
• Apos abrir modal/drawer ou processar resposta com wrapper modal/drawer (mad.js)
• Apos abrir o popover de filtro do grid (_madPositionFilterPopover)

CSS#

Classes do wrapper gerado pelo MAD Select (.mad-sel-* — o <select> original some dentro como .mad-sel-native):

• .mad-sel-control — control visivel que substitui o <select> na tela
• .mad-sel-summary — texto condensado exibido quando o dropdown esta fechado (gerado por summaryText())
• .mad-sel-dropdown — dropdown teleportado pro <body> (escapa de containers com overflow:auto)
• .mad-sel-option — cada linha do dropdown; .mad-sel-checkbox é o checkbox renderizado dentro dela no modo check

---

NUNCA fazer#

{{-- ERRADO: select nativo multiple para multi-selecao com muitas opcoes --}}
<select name="frutas[]" multiple>
    @foreach($frutas as $v => $l)<option value="{{ $v }}">{{ $l }}</option>@endforeach
</select>

{{-- CERTO --}}
<mad-select-check-field name="frutas" :options="$frutas" />

{{-- ERRADO: usar multi-search quando quer linha compacta com "+X itens" --}}
<mad-multi-search-field name="frutas" :options="$frutas" />
{{-- Mostra chips individuais --}}

{{-- CERTO: select-check tem linha condensada --}}
<mad-select-check-field name="frutas" :options="$frutas" />

{{-- ERRADO: options carregadas manualmente no controller quando dbselect-check resolve --}}
@php $cats = Categoria::pluck('nome', 'id')->all(); @endphp
<mad-select-check-field name="cats" :options="$cats" />

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

{{-- ERRADO: montar o select multiplo na mao e inicializar o widget via JS --}}
<select id="x" multiple data-mad-selectcheck></select>
<script>_madInitSelectCheck(document.body);</script>

{{-- CERTO --}}
<mad-select-check-field name="x" :options="$opts" />

---

No-results create + quick register#

Ambos <mad-select-check-field> e <mad-dbselect-check-field> aceitam as props de no-results (mesma API de todos os selects MAD que usam o widget MAD Select — ver dbcombo-rules.md para detalhes):

Prop	Default
no-results-create-action	''
no-results-create-label	'Cadastrar novo'
no-results-create-icon	'plus'
no-results-create-class	'mad-btn mad-btn-primary mad-btn-sm'
no-results-quick-register-action	''
no-results-quick-register-label	'Adicionar'
no-results-quick-register-icon	'check'
no-results-quick-register-class	'mad-btn mad-btn-success mad-btn-sm'
no-results-message	''

<mad-dbselect-check-field name="categorias" label="Categorias"
    model="Categoria" display="nome"
    no-results-create-action="CategoriaForm::show"
    no-results-quick-register-action="CategoriaForm::quickRegister" />