Banner
Tons
Manutenção programada
Você está no modo de teste
Fatura em atraso
Com ações
Fatura em atraso
Que a pessoa dispensa
Manutenção programada
Dentro de um cartão
Você está no modo de teste
Pagamentos
Os últimos 30 dias.
Nenhum pagamento no período.
import { Banner } from '@rivocode/ui'Quando usar
Aviso de página: uma faixa de largura total, no topo da área que ela governa, que fica até o motivo dela acabar. Manutenção programada, fatura em atraso, modo de teste, conta em verificação.
<Banner
tone="warning"
title="Você está no modo de teste"
description="Os pagamentos feitos aqui não cobram cartão de verdade."
/>
Ela diz respeito à conta, ao produto ou à sessão inteira, e não a um trecho do conteúdo. Por isso encosta nas bordas da área, sem canto de cartão, com uma linha neutra embaixo.
Tom e papel
info, success, warning e danger, os quatro tons de estado dos tokens.
O tom decide três coisas ao mesmo tempo: a cor, o ícone e o papel para o leitor
de tela.
dangerewarningsaem comrole="alert", e interrompem o leitor.infoesuccesssaem comrole="status", e esperam a frase terminar.
É a mesma regra do Alert, pelo mesmo motivo: interromper alguém para dizer
"sua conta foi verificada" é falta de educação com quem depende do leitor.
Cor nunca é o único sinal, e por isso o ícone vem sozinho: Info,
CheckCircle2, TriangleAlert e CircleX, o par canônico do lucide. icon
troca o desenho (uma chave inglesa para manutenção, por exemplo), e icon={null}
tira. Ele sai sempre aria-hidden: o texto ao lado já diz o que ele desenha.
Título, descrição e ações
description é obrigatória e é o corpo: o que aconteceu e o que a pessoa faz a
respeito. title é opcional, sai na cor do tom e, quando existe, dá nome à
faixa.
actions recebe os botões, à direita do texto na mesa e embaixo dele no
celular. Use Button com size="sm" e variant="secondary": a borda dele é a
fronteira medida contra o fundo dos quatro tons, nos dois temas. Rótulo longo
quebra dentro do botão em vez de empurrar a página para o lado, e a faixa cabe
em 320px, que é a tela de quem usa zoom de 400%.
<Banner
tone="danger"
title="Fatura em atraso"
description="A fatura de agosto venceu há 5 dias. O acesso da equipe será suspenso em 10/10."
actions={
<Button size="sm" variant="secondary">
Pagar com Pix
</Button>
}
/>
Que a pessoa dispensa
onDismiss liga o xis no fim da faixa, com o nome "Fechar aviso" (ou o que
labels.dismiss disser). Quem some com a faixa é quem chamou: a peça não
guarda estado nenhum, e lembrar que a pessoa já dispensou (nesta sessão, ou para
sempre) é decisão do produto, não da faixa.
const [open, setOpen] = useState(true)
{open && (
<Banner
tone="info"
title="Manutenção programada"
description="O agendamento online fica fora do ar domingo, das 2h às 4h."
onDismiss={() => setOpen(false)}
/>
)}
O que bloqueia não se dispensa. Uma fatura que vai suspender a conta continua na tela até ser paga: tirá-la é resolver o que ela aponta.
Dentro de um painel
flush é a faixa que mora dentro de um Card, de um Sheet ou de um
Dialog, encostada nas bordas dele: o modo de teste de uma conta mostrado no
cartão daquela conta, o aviso de que os dados de um painel estão atrasados.
Ela vai como filha direta do painel, sem respiro em volta, e acerta a linha e o
canto pela posição:
- no topo, pega os cantos de cima do painel e fica só com a linha de baixo;
- no meio, entre o cabeçalho e o conteúdo, ganha a linha de cima também;
- no fim, fica só com a de cima, porque a borda do painel já fecha.
<Card>
<Banner
flush
tone="warning"
title="Você está no modo de teste"
description="Os pagamentos feitos aqui não cobram cartão de verdade."
/>
<CardHeader>
<CardTitle>Pagamentos</CardTitle>
</CardHeader>
</Card>
Sem flush, o canto quadrado da faixa vaza pelo canto arredondado do cartão, e
a linha de baixo dobra a borda dele quando a faixa é a última coisa ali. Se o
aviso fala só de um campo ou de uma tabela dentro do cartão, e não do cartão
inteiro, é Alert.
A faixa decide entre empilhar e pôr as ações ao lado do texto pela largura DELA, e não pela da janela: dentro de um cartão estreito numa tela larga, ela empilha.
Partes
classNames alcança cada nó pelo nome: icon, content (a coluna do texto),
title, description, actions e dismiss.
Quando não usar
- Aviso sobre um trecho do conteúdo é
Alert. OAlertmora junto do que ele fala (o formulário cujo certificado vence, a tabela que veio incompleta), e oBannerfala da página ou da conta inteira. Se o aviso some quando a pessoa troca de tela, eraAlert. - Confirmação do que acabou de acontecer é
Toast. OToastpassa, e oBannerfica: uma faixa "pedido enviado" no topo da tela ainda está lá quando a pessoa volta dez minutos depois, e ela lê aquilo como o estado de agora. - Decisão que precisa de resposta antes de seguir é
AlertDialog. OBannerinforma e deixa trabalhar; oAlertDialogbloqueia a tela até a pessoa escolher.
E não empilhe três faixas no topo. Se há mais de um aviso de página ao mesmo tempo, mostre o mais grave e deixe os outros para a tela onde eles importam.
No React Native
Traduz, com os mesmos quatro tons, o mesmo title, description, actions e onDismiss, e o xis com o mesmo nome acessível ("Fechar aviso"). title e description são string, porque texto no nativo mora dentro de um Text.
A urgência sai por região viva. danger e warning saem com accessibilityRole="alert" e anúncio imediato; info e success saem em região viva educada, que espera a frase terminar. É a mesma divisão do role do web. No iOS, onde a região viva não existe, título e descrição saem pelo anúncio do sistema: nos tons urgentes também ao aparecer, e nos quatro a cada troca de texto.
O ícone não vem sozinho. O pacote nativo não traz biblioteca de ícones, então o icon é opcional e a forma que pinta na cor do tom é a função: icon={({ color, size }) => <TriangleAlert color={color} size={size} />}. As ações ficam embaixo do texto, que é onde cabem na largura do telefone.
flush é só o topo do painel. A faixa pega os cantos de cima do Card e fica com a linha de baixo, como no web. O web acerta a linha também no meio e no fim do painel, pela posição do filho; o React Native não tem seletor de posição, então no meio ou no fim a linha que falta entra por className.
As partes vestem pelo mesmo classNames do web, as seis: icon, content, title, description, actions e dismiss.
API
| Prop | Tipo | Padrão |
|---|---|---|
descriptionobrigatóriaO que aconteceu e o que a pessoa faz a respeito. | ReactNode | sem padrão |
actionsOs botoes da faixa, a direita do texto e embaixo dele no celular. | ReactNode | sem padrão |
classNames | Partial<Record<"actions" | "content" | "description" | "dismiss" | "icon" | "title", string>> | sem padrão |
flushA faixa mora dentro de um painel (`Card`, `Sheet`, `Dialog`), encostada nas bordas dele, e nao no topo da pagina. | boolean | false |
iconTroca o icone do tom. | ReactNode | sem padrão |
labelsOs textos da peca, para trocar o idioma: `dismiss` e o nome do xis, "Fechar aviso" sem ele. | Partial<BannerLabels> | sem padrão |
onDismissLiga o xis de fechar, no fim da faixa. | (() => void) | sem padrão |
titleA frase curta em negrito, antes da descricao. | ReactNode | sem padrão |
toneO tom decide a cor, o icone padrao e o papel para o leitor de tela: `danger` e `warning` saem `role="alert"` e interrompem; `info` e `success` saem `role="status"` e esperam a frase terminar. | "danger""info""success""warning" | "info" |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.