Pular para o conteúdo
Feedback

EmptyState

/componentes/empty-state.mdmarkdown cru, para quem lê com agent em vez de olho

Primeiro uso, num cartão

Nenhum projeto por aqui

Quando você criar o primeiro, ele aparece nesta lista.

Busca sem resultado, num cartão

Nada encontrado para esse filtro

Tente ampliar o período ou limpar o filtro de status.

Primeiro uso, na página inteira

Nenhum aluno ainda

Matricule o primeiro, ou importe a turma inteira de uma planilha.

Busca sem resultado, na página inteira

Nenhum aluno com esse nome

Confira a grafia ou busque pelo número de matrícula.

Importar
import { EmptyState } from '@rivocode/ui'

Quando usar

Estado vazio, com saída.

title e description são obrigatórias, e action é fortemente recomendada. Uma tela que só diz "nenhum resultado" empurra para a pessoa o trabalho de adivinhar o que fazer.

Distinga os dois vazios: primeiro uso ("crie o primeiro projeto") pede ação de criação; busca sem resultado ("nada para esse filtro") pede ação de limpar filtro.

title e description aceitam nó, e não só texto (como no PageHeader e no Timeline). Um número já formatado ou um <strong> no meio da frase cabem: "Nenhum pedido em março".

O empty do DataTable e o do ChartContainer são este mesmo objeto: title, description, action e icon.

Ícone ou ilustração

São dois espaços, e quem escolhe entre eles é o tamanho da área, e não o tipo de vazio. Primeiro uso e busca sem resultado cabem nos dois.

icon é o vazio em área pequena: o cartão, o painel lateral, a coluna de um quadro. Ali um desenho grande empurraria o texto e a ação para fora da vista, e o símbolo só marca o lugar. Ele sai em 32px, forçados em todo SVG, em fg-subtle.

<EmptyState
  icon={<Search />}
  title="Nada encontrado para esse filtro"
  description="Tente ampliar o período ou limpar o filtro de status."
  action={<Button size="sm" variant="secondary">Limpar filtros</Button>}
/>

illustration é o vazio em área grande: a página ou a lista que ocupa a tela. Ali o vazio é o que a pessoa vê primeiro, e um desenho maior explica o que vai morar naquele lugar: EmptyList no primeiro uso, NoResults na busca sem resultado. Nada é forçado: o tamanho é de quem desenha. Quando vem, toma o lugar do icon.

A ilustração pinta com currentColor ou com classe de token, e nunca com cor literal. O sistema veste vários clientes pelo tema, e um desenho com a cor escrita em hexadecimal fica igual na tela de todos eles, e pode sumir no tema escuro. O invólucro já vem em text-fg-subtle, então currentColor acompanha o tema sozinho; para o segundo tom, use fill-accent-subtle, fill-surface-raised e os outros papéis do contrato. Um <img> de arquivo externo não acompanha tema nenhum: prefira o SVG em linha.

O jeito mais curto é uma das nove do @rivocode/ui/illustrations, que já pintam com os papéis e recolorem com o tema: EmptyList no primeiro uso, NoResults na busca sem resultado, EmptyInbox na caixa vazia, NoData no gráfico sem dado. A página Illustration diz qual serve a cada vazio. Desenho próprio continua cabendo, com a mesma regra de cor.

import { EmptyList } from '@rivocode/ui/illustrations'

<EmptyState
  illustration={<EmptyList />}
  title="Nenhum aluno ainda"
  description="Matricule o primeiro, ou importe a turma inteira de uma planilha."
  action={<Button size="sm">Matricular aluno</Button>}
/>

Os dois saem aria-hidden: o título e a descrição já dizem o que o desenho mostra. Se ele disser algo que o texto não diz, o que falta é texto.

Movimento

O estado vazio entra na montagem: esmaece e sobe 4px em --rc-duration-base (animate-enter), o mesmo do Alert. Dentro do DataTable, do QueryBoundary e do ChartContainer, é o que marca que a consulta voltou, e voltou sem nada. Com "reduzir movimento", aparece parado.

Quando não usar

Para o fim de um fluxo (cadastro enviado, pagamento aprovado, ou a falha nele), use Result: ele toma o lugar do formulário e oferece o próximo passo. O EmptyState é porta, e não desfecho: diz o que vai aparecer ali e como começar.

Erro de carga não é vazio. A consulta que falhou é QueryBoundary, ou o isError do DataTable, com o tentar de novo; mostrar "nenhum pedido" quando o servidor não respondeu diz à pessoa que não há nada, e ela acredita. E o aviso que fica ao lado do conteúdo, sem substituí-lo, é Alert.

No React Native

Traduz, com description obrigatória pelo mesmo motivo do web, e com os dois espaços de desenho: icon e illustration, os dois escondidos do leitor de tela.

No React Native a cor não desce da View para o SVG, então o icon aceita também uma função, que recebe o fg-subtle do tema que pinta agora e os mesmos 32 do web:

<EmptyState
  icon={({ color, size }) => <Search color={color} size={size} />}
  title="Nada encontrado para esse filtro"
  description="Tente ampliar o período ou limpar o filtro de status."
/>

A illustration não força nada, como no web: o tamanho é de quem desenha, e a cor vem dos papéis de useRivo().colors, nunca de cor literal. title e description são string, porque moram dentro de um Text. O title é cabeçalho (accessibilityRole="header"), centralizado e na fonte display, como o do Result.

API

PropTipo
descriptionobrigatória0.4.0

Por que esta vazio.

ReactNode
titleobrigatória0.4.0

O que falta, em uma frase.

ReactNode
action0.4.0

A saida.

ReactNode
icon0.4.0

Simbolo de 32px, para o vazio em area pequena: o cartao, o painel lateral, a coluna de um quadro.

ReactNode
illustration

Desenho maior que o icone, para o vazio em area grande: a pagina ou a lista que ocupa a tela.

ReactNode

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@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.