Pular para o conteúdo
Feedback

Banner

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

Tons

Manutenção programada

O agendamento online fica fora do ar domingo, 28/09, das 2h às 4h.
Sua conta foi verificada. Os pagamentos em produção estão liberados.

Com ações

Que a pessoa dispensa

Manutenção programada

O agendamento online fica fora do ar domingo, 28/09, das 2h às 4h.

Dentro de um cartão

Pagamentos

Os últimos 30 dias.

Nenhum pagamento no período.

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

  • danger e warning saem com role="alert", e interrompem o leitor.
  • info e success saem com role="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. O Alert mora junto do que ele fala (o formulário cujo certificado vence, a tabela que veio incompleta), e o Banner fala da página ou da conta inteira. Se o aviso some quando a pessoa troca de tela, era Alert.
  • Confirmação do que acabou de acontecer é Toast. O Toast passa, e o Banner fica: 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. O Banner informa e deixa trabalhar; o AlertDialog bloqueia 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

PropTipoPadrão
descriptionobrigatória

O que aconteceu e o que a pessoa faz a respeito.

ReactNodesem padrão
actions

Os botoes da faixa, a direita do texto e embaixo dele no celular.

ReactNodesem padrão
classNamesPartial<Record<"actions" | "content" | "description" | "dismiss" | "icon" | "title", string>>sem padrão
flush

A faixa mora dentro de um painel (`Card`, `Sheet`, `Dialog`), encostada nas bordas dele, e nao no topo da pagina.

booleanfalse
icon

Troca o icone do tom.

ReactNodesem padrão
labels

Os textos da peca, para trocar o idioma: `dismiss` e o nome do xis, "Fechar aviso" sem ele.

Partial<BannerLabels>sem padrão
onDismiss

Liga o xis de fechar, no fim da faixa.

(() => void)sem padrão
title

A frase curta em negrito, antes da descricao.

ReactNodesem padrão
tone

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

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