Pular para o conteúdo

Padrões de UX / Dados e listas

Filtros e busca

O estado no endereço, os aplicados à vista, e o sem resultado que devolve o filtro.

/padroes/filtros-e-busca.mdo mesmo arquivo que a skill entrega ao agente

A busca acha pelo texto, o filtro recorta por campo, e os dois moram no endereço: o que está aplicado fica à vista, sai com um clique e volta quando a pessoa volta.

O problema

A pessoa filtra a listagem por situação e cliente, abre um registro, aperta voltar, e a lista está crua de novo. Ou manda o link para um colega, que abre a lista inteira. Ou não percebe que há um filtro aplicado desde ontem e acha que os pedidos sumiram. E o filtro que só aplica num botão "Filtrar" escondido no fim do painel faz ela marcar cinco opções antes de descobrir que nada mudou.

Quando usar

Toda listagem que passa de uma tela: a de operação (DataTable), o catálogo de loja, a caixa de entrada, a agenda. A busca entra quando a pessoa sabe o nome do que procura; o filtro, quando ela sabe o tipo.

Onde o filtro mora Quando
Na barra acima da lista até uns quatro campos, os mais usados: situação, período, responsável
Num painel lateral na mesa, Sheet no celular mais que isso, ou faixas e listas longas de opção (preço, marca, categoria)
No cabeçalho da coluna só em tabela de dados, e só para o campo daquela coluna

Quando não usar

  • Lista de menos de uma tela não pede filtro: a pessoa vê tudo.
  • Busca que procura no sistema inteiro (pessoa, pedido, configuração) é o Command com atalho, e não o campo de uma listagem.
  • Filtro que zera a lista sem avisar: a opção que não traria nada mostra "(0)" ou fica desligada.
  • O vazio do filtro não oferece "criar": oferece "Limpar filtros", porque quem filtrou quer o filtro de volta.

As peças

  • SearchInput: a busca da lista, com o limpar e o atalho.
  • Select, Combobox com multiple, DateRangePicker, Slider de faixa, CheckboxGroup: os campos do filtro.
  • FilterBar com filters e onFiltersChange: a fileira do que está aplicado, com o remover de cada um e o "Limpar filtros". É genérico no tipo do filtro: AppliedFilter & { campo: ... } volta inteiro no onRemove.
  • Sheet sem side: o painel de filtros no celular, que sobe de baixo.
  • DataTable com filter, isFetching, noResultsMessage e empty: a lista que filtra, revalida sem piscar e distingue vazio de sem resultado.
  • useDebouncedValue: a busca que espera a pessoa parar de digitar.

Comportamento

  • O estado vai no endereço. Busca, filtros, ordem e página são parâmetros da URL (?situacao=aberta&cliente=482&busca=otica&pagina=2), pelo roteador do projeto. É o que faz voltar do registro devolver a mesma lista, o link compartilhado abrir o mesmo recorte e o recarregar não perder nada. Lembrar entre visitas, com useLocalStorage, é outra coisa, e só para a visão que a pessoa escolheu como dela.
  • Os aplicados ficam à vista, sempre, no FilterBar acima da lista, com o remover de cada um e o "Limpar filtros". No celular, sem reabrir o painel.
  • Na mesa, o filtro aplica na hora, e a contagem do resultado muda junto. A busca aplica depois da pausa, com useDebouncedValue entre 250 e 400 ms.
  • No celular, o painel é um Sheet, e o rodapé dele tem o botão que diz quantos vai mostrar. Ali o filtro só aplica no botão, porque cada toque refazendo a lista atrás da folha não se vê.
  • Filtrar volta para a primeira página, e mantém o resto.
  • A lista de antes fica enquanto a nova chega, com o isFetching: filtro não volta ao esqueleto (espera.md).
  • Sem resultado é diferente de vazio. "Nenhuma nota com estes filtros", com "Limpar filtros", é o noResultsMessage; "Nenhuma nota ainda", com "Emitir a primeira", é o empty.
<div className="flex flex-col gap-3 sm:flex-row sm:items-center">
  <SearchInput
    aria-label="Buscar notas"
    placeholder="Número, cliente ou CNPJ"
    value={search}
    onValueChange={(value) => setParams({ busca: value, pagina: 1 })}
  />
  <Select value={status} onValueChange={(value) => setParams({ situacao: value, pagina: 1 })}>
    <SelectTrigger aria-label="Situação" className="sm:w-48">
      <SelectValue placeholder="Todas as situações" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="aberta">Aberta</SelectItem>
      <SelectItem value="paga">Paga</SelectItem>
      <SelectItem value="cancelada">Cancelada</SelectItem>
    </SelectContent>
  </Select>
</div>
<FilterBar filters={applied} onFiltersChange={(next) => setParams(paramsOf(next))} />

O setParams e o paramsOf são do projeto: escrevem e leem a URL pelo roteador que ele usa.

Texto

  • O placeholder da busca diz por onde ela acha: "Número, cliente ou CNPJ", e não "Buscar…".
  • O filtro aplicado diz o campo e o valor: "Situação: Aberta", e não só "Aberta".
  • O botão do painel no celular diz quantos vai mostrar: "Ver 48 notas".
  • O sem resultado diz o filtro e a saída: "Nenhuma nota aberta deste cliente. Limpar filtros".

Acessibilidade

  • A busca e cada filtro têm rótulo, mesmo quando o visível é só o placeholder: aria-label no campo, ou o FieldLabel escondido com sr-only.
  • A contagem do resultado sai numa região viva educada ("48 notas"), para quem não vê a lista mudar.
  • O xis de cada filtro aplicado nomeia o que remove ("Remover Situação: Aberta"): o FilterBar já faz.
  • Filtrar não leva o foco embora do campo que a pessoa está usando.

No celular e no nativo

No celular a busca fica no topo, os filtros num botão "Filtros (2)" que abre a Sheet, e a fileira do FilterBar rola na horizontal logo abaixo, com o limpar ancorado fora do que rola. No @rivocode/ui-native o SearchInput pede value e onValueChange, o FilterBar traduz, e o estado vai nos parâmetros da rota do router nativo, pela mesma razão da URL: voltar do detalhe devolve o recorte.

A loja tem o seu jeito de filtrar, com contagem por opção e o carregar mais: comercio.md.

Os blocos que o aplicam

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.