Search

Campo de busca com ícone de lupa, botão de limpar e suporte a debounce. Use `mk-search` para buscas em listagens, tabelas e páginas de conteúdo.

O mk-search é o campo de busca do Makuco UI. Diferentemente do mk-input, não possui rótulo nem integração com formulários nativos — é um campo utilitário focado exclusivamente na experiência de busca. O ícone de lupa fica sempre à direita; quando há valor, o botão × e um divisor surgem antes dele.

Possui duas variantes: default (pill, 40px) e subtle (arredondado, 36px) — ambas com suporte a debounce, estado de carregamento, texto auxiliar e mensagem de erro.

Padrão

import { MkSearch } from '@db1/makuco-ui-react';

<MkSearch placeholder="Buscar..." />

<mk-search placeholder="Buscar..."></mk-search>

Sutil

Use variant="subtle" em contextos de maior densidade: cabeçalhos de tabela, toolbars compactas. Borda arredondada (radius-md), altura 36px, tipografia 12px e borda mais leve.

<MkSearch variant="subtle" placeholder="Buscar..." />

<mk-search variant="subtle" placeholder="Buscar..."></mk-search>

Com valor e botão de limpar

Quando value está preenchido, o botão ×, um divisor e o ícone de lupa aparecem agrupados à direita. Clicar no × emite mkClear e reseta o campo para vazio. Pressionar Escape tem o mesmo efeito.

<MkSearch
  value="Design system"
  placeholder="Buscar..."
  onMkClear={() => console.log('cleared')}
/>

<mk-search
  value="Design system"
  placeholder="Buscar..."
  (mkClear)="onClear()"
></mk-search>

Texto auxiliar

Use supportText para orientar o usuário sobre o que pode ser buscado. O texto aparece abaixo do campo e é referenciado via aria-describedby.

<MkSearch
  supportText="Busque por nome, código ou categoria"
  placeholder="Buscar..."
/>

<mk-search
  helper-text="Busque por nome, código ou categoria"
  placeholder="Buscar..."
></mk-search>

Estado de erro

Defina errorMessage para colocar o componente em estado inválido: borda vermelha, mensagem de erro abaixo do campo. Quando errorMessage e supportText estão ambos definidos, apenas errorMessage é exibido.

<MkSearch
  value="???"
  errorMessage="Nenhum resultado encontrado"
/>

<mk-search
  value="???"
  error-message="Nenhum resultado encontrado"
></mk-search>

Com debounce

Use debounce (em ms) para reduzir a frequência de chamadas em buscas que fazem requisições ao servidor. O evento mkChange só é emitido após o período de inatividade configurado.

<MkSearch
  debounce={300}
  placeholder="Buscar..."
  onMkChange={(e) => fetchResults(e.detail)}
/>

<mk-search
  [debounce]="300"
  placeholder="Buscar..."
  (mkChange)="fetchResults($event.detail)"
></mk-search>

Loading

Defina loading para exibir um spinner enquanto a busca está em andamento. O botão de limpar é ocultado automaticamente durante o carregamento.

const [loading, setLoading] = React.useState(false);

<MkSearch
  loading={loading}
  placeholder="Buscar..."
  onMkChange={async (e) => {
    setLoading(true);
    await fetchResults(e.detail);
    setLoading(false);
  }}
/>

<mk-search
  [loading]="isLoading"
  placeholder="Buscar..."
  (mkChange)="onSearch($event.detail)"
></mk-search>

Desabilitado

<MkSearch disabled placeholder="Campo desabilitado" />

<mk-search disabled placeholder="Campo desabilitado"></mk-search>

Somente leitura

<MkSearch readonly value="Valor somente leitura" />

<mk-search readonly value="Valor somente leitura"></mk-search>

Props — mk-search

Prop	Tipo	Padrão	Descrição
`variant`	`"default" \| "subtle"`	`"default"`	Variante visual. `default`: pill, 40px, body-sm. `subtle`: arredondado, 36px, caption.
`value`	`string`	—	Valor controlado do campo.
`placeholder`	`string`	—	Texto exibido quando o campo está vazio.
`supportText`	`string`	—	Texto de suporte exibido abaixo do campo quando não há `errorMessage`.
`errorMessage`	`string`	—	Mensagem de erro. Quando definida, ativa o estado inválido (borda vermelha).
`name`	`string`	—	Atributo `name` nativo.
`debounce`	`number`	`0`	Delay em ms para o evento `mkChange`. Quando `0`, o evento é emitido imediatamente.
`loading`	`boolean`	`false`	Exibe um spinner no lugar do botão de limpar.
`disabled`	`boolean`	`false`	Desabilita o campo, impedindo a interação do usuário.
`readonly`	`boolean`	`false`	Torna o campo somente leitura.
`label`	`string`	`"Buscar"`	Rótulo acessível para o landmark `role="search"` e o input nativo.

Eventos

Evento	Componente	Payload	Descrição
`mkChange`	`mk-search`	`string`	Emitido após `debounce` ms de inatividade (ou imediatamente se `debounce = 0`) com o valor atual. Ao limpar via × ou Escape, é emitido imediatamente com `""`.
`mkClear`	`mk-search`	`void`	Emitido ao clicar no botão × ou ao pressionar Escape com valor preenchido.
`mkFocus`	`mk-search`	`void`	Emitido quando o campo recebe foco.
`mkBlur`	`mk-search`	`void`	Emitido quando o campo perde o foco.

Acessibilidade

O mk-search implementa o padrão de landmark de busca da especificação WAI-ARIA.

O host recebe role="search" — landmark nativo reconhecido por leitores de tela para identificar regiões de busca na página.
O aria-label do landmark e do input nativo são controlados pela prop label (padrão: "Buscar"). Personalize quando houver múltiplos campos de busca na mesma página.
O ícone de lupa é aria-hidden="true" — puramente decorativo.
O spinner tem role="status" e aria-label="Carregando resultados".
O botão de limpar possui aria-label="Limpar busca" e pode ser ativado por teclado (Enter ou Space).
supportText e errorMessage são vinculados ao input via aria-describedby.

Tecla	Comportamento
`Escape`	Limpa o campo quando há valor e o campo não está desabilitado ou somente leitura.
`Tab`	Move o foco para o próximo elemento interativo (input → botão ×, quando visível).
`Enter` / `Space` (no botão ×)	Limpa o campo e retorna o foco para o input.

Search

On this page