Pular para o conteúdo
Feedback

ToastViewport

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

Aviso de sucesso

A área de avisos já vem montada pelo RivoProvider. A aplicação só chama o gancho.

Aviso de uma espera

Com promise, o mesmo aviso atravessa a espera e vira o resultado.

Excluir com desfazer

  • Projeto Atlas
  • Projeto Borealis
  • Projeto Cometa
Importar
import { ToastViewport } from '@rivocode/ui'

Quando usar

A área onde os avisos aparecem. Ela já vem montada dentro do RivoProvider, então na prática o aplicativo nunca a escreve: chama useToast() e pronto.

const toast = useToast()

toast.add({ title: 'Pedido 10516 confirmado', description: 'O comprovante foi para o e-mail.' })

O gancho

useToast() devolve quatro funções, e nenhuma delas precisa de estado seu:

Função O que faz
add(options) Cria o aviso e devolve o id dele
update(id, options) Reescreve um aviso que ainda está na tela
close(id) Tira o aviso antes da hora
promise(promessa, estados) Um aviso só para as três fases de uma espera

O options do add tem title, description, type e timeout. O type escolhe o tom no mesmo vocabulário do Alert, info, success, warning e danger; sem ele o aviso sai neutro, que é o padrão e o que serve para a maior parte das confirmações. timeout: 0 deixa o aviso na tela até alguém fechar.

O tom mora no fundo e no ícone

O aviso de tom pinta o fundo tingido e põe o ícone do tom à esquerda, na cor do tom: Info, CheckCircle2, TriangleAlert e CircleX, o mesmo par do Alert (o error desenha o do danger). O título fica em fg e a descrição em fg-muted, porque cor nunca é o único sinal, e o ícone carrega o tom sem pintar o texto. O neutro e o loading saem sem ícone.

icon troca o símbolo de um aviso só, e null tira. Ele vale no add, no update e em cada fase do promise:

toast.add({ title: 'Produto favoritado', type: 'success', icon: <Heart /> })
toast.add({ title: 'Sincronização pausada', type: 'warning', icon: null })

A borda continua neutra, e é diferente do Alert de propósito. O Alert mora no fluxo da página, e o fundo tingido já é a borda dele; o aviso flutua sobre qualquer coisa, com sombra, e a borda é a borda da camada, a mesma do Menu e do Popover, que separa o aviso de um conteúdo do mesmo tom embaixo dele.

O xis de cada aviso se chama "Fechar aviso", e a região que o leitor de tela anuncia se chama "Notificações". Para trocar o idioma, passe toastLabels={{ dismiss: "Dismiss", region: "Notifications" }} ao RivoProvider, que entrega o labels à área.

toast.promise(publishProduct(), {
  loading: { title: 'Publicando o produto…' },
  success: (code) => ({ title: `Produto ${code} publicado na loja` }),
  error: { title: 'A publicação falhou' },
})

O promise existe para a espera não virar três avisos empilhados. É um aviso só, que troca de texto e de tom conforme a promessa resolve; a alternativa, add na saída e outro add na volta, deixa o "enviando" na tela ao lado do "enviado".

Cabem três avisos na tela ao mesmo tempo. O quarto entra e o mais antigo sai de vista até um dos outros fechar, e aí volta, com o xis funcionando: um aviso com timeout: 0 continua esperando a pessoa fechar, em vez de ficar visível e sem resposta ao clique.

O objeto que o gancho devolve tem identidade estável entre renderizações, então ele pode entrar na lista de dependências de um efeito sem laço. O gerenciador da Base UI por baixo não tem essa garantia, e absorver isso é trabalho da biblioteca, não de quem a usa.

Desfazer

A ação reversível ganha desfazer, e não confirmação: faz na hora, e o aviso oferece a volta por alguns segundos. actionProps desenha o botão dentro do aviso, e é quem o pede que decide o que ele faz e se o aviso fecha junto:

const toast = useToast()

function remove(project: Project) {
  removeFromList(project.id)
  const id = toast.add({
    title: `Projeto ${project.name} excluído`,
    timeout: 8000,
    actionProps: {
      children: 'Desfazer',
      onClick: () => {
        restore(project)
        toast.close(id)
      },
    },
  })
}

Dê mais tempo que o padrão ao aviso com desfazer: ler, entender e alcançar o botão leva mais que ler um "salvo". Sem actionProps, o aviso não ganha botão nenhum além do xis.

O botão do aviso no leitor de tela

O aviso é lido em voz alta quando entra, e o botão dele se alcança pelo teclado: F6 leva o foco para a área de avisos, de qualquer ponto da página, e o Tab anda entre o aviso, o botão e o xis. O xis fica escondido do leitor de tela até a área receber foco, para o anúncio não terminar em "Fechar aviso".

priority: 'high' muda duas coisas. O anúncio passa a interromper o que o leitor estava falando, e o aviso inteiro fica fora da leitura linha a linha (aria-hidden) até receber foco, para não ser lido duas vezes. Quem navega pela leitura linha a linha não acha o botão nesse caso, então o aviso urgente com actionProps precisa do mesmo caminho fora dele, como o sino da central de notificações ou um link na própria página. Use high só no que não pode esperar: um pedido novo, uma sessão que vai expirar.

Onde o aviso aparece

O padrão é bottom-right, que é o canto que menos disputa com o conteúdo: cabeçalho, título e ação principal moram em cima. Para mudar, escolha no provider, e não com CSS por cima:

<RivoProvider toastPosition="top-center">
  <App />
</RivoProvider>

Os seis cantos são top-left, top-center, top-right, bottom-left, bottom-center e bottom-right; o tipo ToastPosition é essa união, para quando o canto vem de uma configuração e não de uma constante.

O aviso entra sempre pela borda mais próxima do canto escolhido. Um aviso ancorado à esquerda que deslizasse da direita atravessaria a tela inteira para chegar ao lugar, e o olho seguiria o movimento errado até perceber que o texto já estava lá.

Vale sair do padrão quando o aviso responde a uma ação que acontece longe dali, ou quando aquele canto já está ocupado por outra coisa fixa, como um botão flutuante.

Barra fixa embaixo. Nos três cantos de baixo, a distância da borda é --rc-toast-bottom (1rem sem ela) mais a área do gesto do celular. A tela que tem uma barra presa embaixo, como a navegação do celular ou o botão de comprar, declara a altura dela nessa variável, e o aviso aparece acima da barra em vez de cobri-la:

@media (max-width: 767px) {
  :root {
    --rc-toast-bottom: calc(4.5rem + 0.5rem);
  }
}

O foco depois de fechar

Fechar um aviso pelo teclado não joga o foco para o começo da página. Ele vai para o aviso vizinho quando há outro na pilha, e, fechado o último, volta para onde estava antes de entrar nos avisos. Sem esse lugar, fica na região dos avisos, e o próximo Tab segue dali. O xis tem 22 pixels desenhados e área de toque de 30.

Quando não usar

Aviso é para o que já aconteceu, e o que já aconteceu não precisa de resposta. Se a pessoa tem de decidir algo, use AlertDialog. Se a informação precisa ficar na tela enquanto ela trabalha, use Alert, que mora no fluxo da página e não some sozinho.

Erro de formulário também não é aviso: ele pertence ao campo que errou, via FieldError, onde a pessoa está olhando e pode corrigir.

No React Native

No React Native esta peça é useToast - não se monta nada: o RivoProvider já traz a fiação, e o hook é o mesmo, com as quatro funções: add devolve o id, type escolhe o tom no vocabulário do Alert, timeout: 0 deixa o aviso até o close(id), e update e promise reescrevem o aviso que está na tela. Aqui o title e a description são string, porque o aviso é lido em voz alta, e não há xis: o aviso sem botão não recebe toque, então o que fica sai pelo close. Sem timeout, ele sai em 4 segundos, e não nos 5 do web. O actionProps do web, que põe o desfazer dentro do aviso, existe aqui com onPress no lugar do onClick ({ children: "Desfazer", onPress }), e só o aviso com botão recebe toque. O aviso sobe e desce com as durações do web, e aparece parado quando o sistema pede para reduzir movimento. O tom fica no fundo, sem borda saturada, como no Alert nativo, e o aviso de tom pousa sobre a surface-raised, para o que está embaixo não aparecer através dele. O pacote não traz ícone, então não há o símbolo do tom por padrão: icon aceita um nó ou a função ({ color, size }) => <CircleX color={color} size={size} />, que recebe a cor do tom, e só com ele o título passa a fg; sem ícone, o título continua na cor do tom, porque é o único sinal além do fundo. No web o ícone do tom vem por padrão, e o título é sempre fg. O aviso aparece por cima do Modal aberto da casa (Dialog, AlertDialog, Sheet, Tour e ImageViewer): o Modal do React Native é uma janela própria e cobriria a raiz, então o aviso passa a morar no Modal de cima enquanto ele está aberto, uma vez só, e volta para a raiz quando ele fecha. Modal escrito à mão no app não leva o aviso. A tabela de paridade tem o resto do catálogo.

API

PropTipoPadrão
containerobrigatória0.4.0

Onde o portal ancora.

HTMLElement | nullsem padrão
labels

Os textos da peca, para trocar o idioma: `dismiss` e o nome do xis de cada aviso, "Fechar aviso" sem ele; `region` e o nome da regiao que o leitor de tela anuncia, "Notificações" sem ele.

Partial<ToastLabels>sem padrão
position0.4.0

Onde os avisos aparecem.

ToastPosition"bottom-right"
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, ToastViewportState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

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.