SearchField

Campo de busca com ícone, botão de limpar e envio por Enter.

O SearchField é o campo de busca do Admin: ícone de lupa, texto e um botão de limpar que só aparece quando há texto. É a peça de busca da barra de filtros da lista de Pedidos. Para texto livre em formulários use TextField; para escolher entre opções conhecidas, Select.

import { SearchField } from "@rastreio-x/ui";

Padrão

A composição é SearchField.Group com SearchIcon, Input e ClearButton. Sem rótulo visível, aria-label é obrigatório.

Variantes

primary tem sombra suave; secondary não tem, e é a variante para usar em cartões e barras de filtro.

Filtro ao digitar

Com value e onChange você filtra a cada tecla. Serve para listas locais pequenas; anuncie o resultado em uma região aria-live.

PED-1042 · Marina Souza
PED-1041 · Rafael Lima
PED-1040 · Beatriz Alves
PED-1039 · Marina Souza

Envio por Enter

onSubmit recebe o texto ao pressionar Enter e onClear avisa quando o botão (ou Esc) limpa o campo. É o padrão da lista de Pedidos: a busca vai ao servidor só quando a pessoa confirma.

Nenhuma busca enviada

Estados

Preenchido, com o botão de limpar visível, e desabilitado.

Anatomia

SearchField
├── SearchField.ClearButton
├── SearchField.Group
├── SearchField.Input
└── SearchField.SearchIcon

SearchField.Group: o contêiner que desenha o campo.
SearchField.SearchIcon: a lupa, decorativa.
SearchField.Input: o campo de texto, com placeholder.
SearchField.ClearButton: limpa o texto; some quando o campo está vazio.

Propriedades

Raiz (SearchField):

SearchField
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoComplete`	`string`	-	Tipo de preenchimento automático que o navegador pode oferecer.
`autoCorrect`	`string`	-	Ativa ou desativa a autocorreção do teclado.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<SearchFieldRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<SearchFieldRenderProps>`	`'react-aria-SearchField'`	Classes CSS aplicadas ao elemento.
`defaultValue`	`string`	-	Valor inicial, para uso não controlado.
`enterKeyHint`	`'search' \| 'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'send'`	-	Rótulo sugerido para a tecla Enter em teclados virtuais.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`id`	`string`	-	Identificador único do elemento.
`inputMode`	`'email' \| 'text' \| 'search' \| 'none' \| 'tel' \| 'url' \| 'numeric' \| 'decimal'`	-	Tipo de teclado virtual sugerido.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isReadOnly`	`boolean`	-	Permite selecionar e copiar o valor, mas não alterá-lo.
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`maxLength`	`number`	-	Máximo de caracteres aceitos.
`minLength`	`number`	-	Mínimo de caracteres exigidos.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: string) => void)`	-	Chamada quando o valor ou a seleção muda.
`onClear`	`(() => void)`	-	Chamada ao limpar o valor.
`onSubmit`	`((value: string) => void)`	-	Chamada ao enviar o formulário.
`pattern`	`string`	-	Expressão regular que o valor deve satisfazer.
`render`	`DOMRenderFunction<'div', SearchFieldRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`spellCheck`	`string`	-	Ativa ou desativa a verificação ortográfica.
`style`	`StyleOrFunction<SearchFieldRenderProps>`	-	Estilos em linha aplicados ao elemento.
`type`	`'email' \| 'password' \| 'text' \| 'search' \| (string & {}) \| 'tel' \| 'url'`	`'search'`	Tipo do elemento; define o comportamento nativo (em botões, `button`, `submit` ou `reset`).
`validate`	`((value: string) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	-	Variante visual do componente.

Campo (SearchField.Input):

SearchField.Input
Prop	Tipo	Padrão	Descrição
`children`	`React.ReactNode`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<InputRenderProps>`	`'react-aria-Input'`	Classes CSS aplicadas ao elemento.
`placeholder`	`string`	-	Texto de apoio exibido quando o campo está vazio.
`render`	`DOMRenderFunction<'input', InputRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<InputRenderProps>`	-	Estilos em linha aplicados ao elemento.

Botão de limpar (SearchField.ClearButton):

SearchField.ClearButton
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<ButtonRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ButtonRenderProps>`	`'react-aria-Button'`	Classes CSS aplicadas ao elemento.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`formAction`	`string \| ((formData: FormData) => void \| Promise<void>)`	-	URL ou função que processa o envio; sobrescreve a ação do formulário.
`formEncType`	`string`	-	Codificação dos dados enviados pelo formulário.
`formMethod`	`string`	-	Método HTTP do envio do formulário.
`formNoValidate`	`boolean`	-	Desativa a validação nativa do formulário no envio.
`formTarget`	`string`	-	Janela de destino do envio; sobrescreve a do formulário.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isPending`	`boolean`	-	Estado de carregamento: bloqueia novos cliques, mantém o foco e anuncia o estado a leitores de tela.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`preventFocusOnPress`	`boolean`	-	Impede que o foco vá para o elemento ao pressioná-lo. Pode prejudicar a acessibilidade.
`render`	`DOMRenderFunction<'button', ButtonRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<ButtonRenderProps>`	-	Estilos em linha aplicados ao elemento.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	Tipo do elemento; define o comportamento nativo (em botões, `button`, `submit` ou `reset`).
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'default'`	-	Variante visual do componente.

Animações

CSS
indicativo

O botão de limpar aparece e some com uma transição curta de opacidade do HeroUI, e o foco troca o fundo do campo com transição de cor. Com prefers-reduced-motion, a folha global da fachada reduz tudo a 0,01 ms.

Acessibilidade

O campo tem papel searchbox; o grupo ao redor fica dentro de uma região role="search" quando está num FilterBar.
Sem Label visível, passe aria-label ao SearchField: busca sem nome acessível é falha.
Esc limpa o texto; Enter dispara onSubmit. O botão de limpar é focável e tem nome (Limpar busca).
A lupa é aria-hidden. Anuncie contagem de resultados em uma região aria-live="polite".
O anel de foco mantém 3:1 contra a superfície; o texto, 4,5:1.

Boas práticas

Faça

Placeholder que diz o que dá para buscar, como Buscar por Pedido, Cliente ou e-mail.

Evite

Placeholder genérico como Buscar, ou campo de busca sem `aria-label`.

Prefira onSubmit quando a busca vai ao servidor; filtre ao digitar só em listas locais.
Mostre o estado vazio explicando que nenhum item combina e como limpar a busca.
Use variant="secondary" em cartões e barras de filtro.
Mantenha o texto buscado na URL quando a lista é uma página navegável.

Relacionados

FilterField a barra de filtros onde a busca mora.
TextField para texto livre em formulários.
Select para opções conhecidas.
Input o campo simples de uma linha.