EmptyState
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.
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
| Prop | Tipo |
|---|---|
descriptionobrigatória0.4.0Por que esta vazio. | ReactNode |
titleobrigatória0.4.0O que falta, em uma frase. | ReactNode |
action0.4.0A saida. | ReactNode |
icon0.4.0Simbolo de 32px, para o vazio em area pequena: o cartao, o painel lateral, a coluna de um quadro. | ReactNode |
illustrationDesenho 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.