mad-search-field — Componentes (Admin)

Search box de texto livre: um <input type="search"> com ícone de lupa e botão de limpar (x), pensado para toolbars de filtro/listagem. Não é um select — não recebe :options, não tem dropdown e não seleciona um valor de uma lista. Para isso use <mad-unique-search-field> (options em memória) ou <mad-dbcombo-field> / <mad-dbunique-search-field> (busca no banco).

Integra com MadForm via mad:model automático e registra-se no MadFormRegistry como tipo 'search'. Suporta preenchimento de valor inicial via MadRenderContext (ex: $form->fill($record) ou re-render após onReload).

Props

Prop	Tipo	Default	Descrição
name	string	''	Nome do campo
label	string	''	Label
placeholder	string	'Pesquisar...'	Placeholder
width	string	''	Largura CSS do wrapper
max-width	string	''	`max-width` CSS do wrapper
hint	string	''	Texto de ajuda abaixo do campo
error	string	''	Mensagem de erro (aplica estilo de erro)
required	bool	false	Campo obrigatório (mostra asterisco)
disabled	bool	false	Campo desabilitado
attrs	string	''	Atributos HTML extras

Uso básico

<mad-search-field name="busca" label="Buscar" placeholder="Nome ou código..." />

Em filtro de listagem

<mad-form submit="onReload">
    <mad-form-grid :cols="2">
        <mad-search-field name="busca" label="Busca rápida" placeholder="Nome, email, CPF..." />
        <mad-dbcombo-field name="status" label="Status" model="Estado" display="nome" />
    </mad-form-grid>
    <mad-form-actions>
        <mad-btn type="submit" variant="primary" icon="search">Buscar</mad-btn>
    </mad-form-actions>
</mad-form>

public function onReload(): MadResponse
{
    $data = $this->form->getData();

    $registros = SystemUsers::query()
        ->when($data['busca'] ?? null, fn ($q, $busca) => $q->where('nome', 'like', "%{$busca}%"))
        ->get();

    return $this->grid->reload($registros);
}

<mad-search-field name="q" placeholder="Pesquisar..." width="240px" />

Eventos

<mad-search-field> é um <input> simples — aceita mad:change="metodo" via attrs (mecanismo genérico do MAD, igual a qualquer outro input), disparado no evento nativo change (blur com valor alterado, ou Enter):

<mad-search-field name="busca" label="Buscar"
    attrs='mad:change="onBuscaChange"' />

public function onBuscaChange(string $value): MadResponse
{
    return $this->grid->reload(
        SystemUsers::where('nome', 'like', "%{$value}%")->get()
    );
}

Comportamento

Ícone de lupa: fixo à esquerda do input (Lucide search), puramente visual.
Botão de limpar (x): aparece somente quando o campo tem valor (estado Alpine local). Ao clicar, zera o valor e dispara manualmente um evento input no campo — garante que mad:model/mad:model.live e outros listeners reajam à limpeza mesmo sem digitação do usuário.
mad:model automático: se attrs não tiver mad:model/data-mad-model, o componente injeta mad:model="<name>" sozinho — não precise declarar.
Valor inicial: resolvido via MadRenderContext (preenchido por $form->fill($record) ou re-render do form), igual a <mad-input-field>.
Validação: client-side limitada a required (asterisco visual). Validação real é server-side, no controller.

Quando usar search-field vs outros campos de busca

Cenário	Usar
Texto livre para filtrar uma listagem/grid (não seleciona valor)	`<mad-search-field>`
Selecionar 1 valor de uma lista já em memória, com busca	`<mad-unique-search-field>`
Selecionar 1 valor com busca server-side (lista grande, 200+)	`<mad-dbunique-search-field>`
Selecionar 1 valor de uma query do banco (lista média, client-side)	`<mad-dbcombo-field>`
Selecionar múltiplos valores com busca	`<mad-multi-search-field>`
Texto livre com autocomplete/sugestões do banco	`<mad-dbentry-field>`
Busca com modal grid (várias colunas, paginação)	`<mad-seek>`

NUNCA fazer

{{-- ERRADO: usar search-field para selecionar um valor de uma lista --}}
<mad-search-field name="cliente_id" label="Cliente" />
{{-- search-field é texto livre, não tem :options nem dropdown --}}

{{-- CERTO: unique-search ou dbcombo selecionam de uma lista --}}
<mad-unique-search-field name="cliente_id" label="Cliente" :options="$clientes" />
<mad-dbcombo-field name="cliente_id" label="Cliente" model="Cliente" display="nome" />

{{-- ERRADO: passar :options para search-field (prop não existe no componente) --}}
<mad-search-field name="busca" :options="$itens" />

{{-- CERTO: search-field não recebe options — é só um input de texto --}}
<mad-search-field name="busca" label="Buscar" />

{{-- ERRADO: input nativo reimplementando ícone + botão de limpar --}}
<div style="position:relative;">
    <input type="search" name="busca">
    <button type="button" onclick="this.previousElementSibling.value=''">x</button>
</div>

{{-- CERTO --}}
<mad-search-field name="busca" label="Buscar" />

Props#

Uso básico#

Em filtro de listagem#

Sem label (toolbar compacta)#

Eventos#

Comportamento#

Quando usar search-field vs outros campos de busca#

NUNCA fazer#