Notification

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-notification é o painel oficial do GovBR-DS para centralização e exibição de avisos, comunicados e notificações do sistema, tipicamente acionado a partir de um botão com ícone de sino no cabeçalho.

Para que serve

• Central de notificações do usuário: Reúne em uma única gaveta ou painel suspenso todas as mensagens, lembretes e alertas direcionados à pessoa usuária.
• Estruturação por abas e contexto: Permite organizar notificações por abas (ex.: "Todas", "Não lidas", "Arquivadas") com ações rápidas (marcar como lida, excluir).
• Gerenciamento de abertura e foco: Controla abertura, fechamento, tecla Escape e foco acessível.

Quando utilizar

• Utilize quando:
  • O sistema gerar eventos e comunicados assíncronos que a pessoa usuária precise consultar a qualquer momento.
• Evite e prefira outro componente quando:
  • A mensagem for uma resposta imediata a uma ação na tela atual (prefira br-message).
  • O aviso exigir confirmação bloqueadora antes de continuar (prefira br-modal).

Composição e Subcomponentes

Subcomponente	Papel	Regra de uso
br-notification-body	Corpo principal. Contém a listagem das notificações e abas de filtro opcionais.	Declarado no slot padrão do br-notification.
br-notification-header	Cabeçalho do painel. Exibe o título, avatar do usuário, contadores e botão de fechar.	Declarado no slot header ou topo do br-notification.
br-notification-item	Notificação individual. Representa cada mensagem com ícone, data, texto e ações.	Declarado dentro do br-notification-body.
br-notification	Orquestrador principal. Gerencia a superfície flutuante, estado de visibilidade e foco.	Contêiner raiz obrigatório.

Como os subcomponentes se relacionam

O br-notification projeta o painel suspenso:

1. O cabeçalho (br-notification-header) contextualiza o painel e fornece o botão de dispensa.
2. O corpo (br-notification-body) agrupa e organiza a coleção de itens (br-notification-item).
3. Cada item (br-notification-item) expõe eventos de clique e ações individuais (como marcar como lida).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

Propriedades

closeOnOutsideClick

Atributo	close-on-outside-click
Descrição	Fecha o painel ao clicar fora da superfície.
Tipo	boolean
Valor padrão	true

closeOnTriggerClick

Atributo	close-on-trigger-click
Descrição	Fecha o painel ao clicar novamente no acionador.
Tipo	boolean
Valor padrão	true

customId

Atributo	custom-id
Descrição	Identificador único do componente. Quando omitido, um valor é gerado automaticamente. > Padrão: valor único gerado por generateUniqueId().
Tipo	string
Valor padrão	generateUniqueId()

internalScroll

Atributo	internal-scroll
Descrição	Habilita rolagem apenas na região de itens, preservando cabeçalho e abas fixos.
Tipo	boolean
Valor padrão	true

isStatic

Atributo	is-static
Descrição	Define se o painel de notificações deve ser renderizado de forma estática (inline). Quando verdadeiro, o posicionamento absoluto é desativado. Ideal para centrais de notificações fixas ou documentação.
Tipo	boolean
Valor padrão	false

label

Atributo	label
Descrição	Nome acessível do painel de notificações. Exposto via aria-label. (obrigatório)
Tipo	string
Valor padrão	---

maxHeight

Atributo	max-height
Descrição	Sobrescreve a altura máxima do painel. Por padrão, o CSS aplica calc(100vh - 86px) via token --notification-height.
Tipo	string
Valor padrão	---

maxWidth

Atributo	max-width
Descrição	Sobrescreve o max-width do painel. Por padrão, o CSS aplica max-width: 50vw em viewports ≥576px conforme a especificação do Design System.
Tipo	string
Valor padrão	---

mobileFullscreen

Atributo	mobile-fullscreen
Descrição	Faz o painel ocupar toda a largura disponível em viewports pequenas.
Tipo	boolean
Valor padrão	true

open

Atributo	open
Descrição	Controla se o painel de notificações está aberto.
Tipo	boolean
Valor padrão	false

placement

Atributo	placement
Descrição	Define o posicionamento do painel em relação ao acionador. Valores inválidos usam bottom-end.
Tipo	"bottom-end" | "bottom-start" | "top-end" | "top-start"
Valor padrão	'bottom-end'

width

Atributo	width
Descrição	Largura explícita do painel. Quando não definida, o painel dimensiona conforme o conteúdo, respeitando o max-width definido por spec ou pelo prop maxWidth.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"default"	Região principal da lista de notificações.
"footer"	Região opcional para ações complementares, como "ver todas".
"header"	Região superior do componente, para uso com subcomponentes de cabeçalho ou conteúdo customizado.
"tabs"	Região opcional para navegação por abas.
"trigger"	Elemento acionador externo responsável por abrir e fechar o painel.

Eventos

Evento	Descrição	Depreciação	Propagação
brNotificationClose	Informa que o painel foi fechado.	---	true
brNotificationItemClick	Expõe a interação com um item da lista.	---	true
brNotificationOpen	Informa que o painel foi aberto.	---	true
brNotificationTabChange	Informa troca de aba quando o componente possuir navegação por tabs.	---	true
brOpenChange	Informa a mudança de estado aberto/fechado do painel.	---	true

Métodos

focusFirstItem

Descrição	Move o foco para o primeiro item interativo da lista.
Assinatura	focusFirstItem() => Promise<void>
Parâmetros	---

focusTrigger

Descrição	Move o foco de volta para o acionador.
Assinatura	focusTrigger() => Promise<void>
Parâmetros	---

hide

Descrição	Fecha o painel de notificações.
Assinatura	hide(reason?: NotificationCloseReason) => Promise<void>
Parâmetros	reason:

show

Descrição	Abre o painel de notificações.
Assinatura	show() => Promise<void>
Parâmetros	---

toggle

Descrição	Alterna o estado aberto/fechado.
Assinatura	toggle() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"base"	Superfície principal do painel.
"body"	Região principal do componente.
"close-button"	Botão de fechar do painel.
"divider"	Divisor entre itens da lista.
"footer"
"header"	Região superior do componente.
"list"	Região com rolagem onde os itens são exibidos.
"tabs"	Região de abas, quando existir.

Acessibilidade

O painel é uma superfície ancorada a um acionador. O label (obrigatório) vira o aria-label do painel, dando a ele um nome acessível. O estado open é refletido e o acionador recebe aria-expanded sincronizado.

Foco

• Ao abrir, o foco vai para o primeiro elemento focável do painel.
• Tab/Shift+Tab circulam entre os focáveis do painel enquanto ele está aberto.
• Ao fechar, o foco volta para o elemento que estava focado antes da abertura.

Teclado e fechamento

• Escape fecha o painel.
• close-on-outside-click (padrão) fecha ao clicar fora; close-on-trigger-click (padrão) permite alternar pelo próprio acionador.

Conteúdo

• Use os subcomponentes de cabeçalho, abas e itens para estrutura semântica.
• Abas emitem brNotificationTabChange; itens emitem brNotificationItemClick — reflita a mudança de contexto para tecnologias assistivas quando a navegação alterar o conteúdo visível.

Movimento

Entrada e saída do painel respeitam prefers-reduced-motion: reduce.

Dependências

Subcomponentes

• br-notification-body
• br-notification-header
• br-notification-item

Migração de <br-notification> (1.x → 2.x)

Na 1.x, a notificação recebia uma coleção de objetos em notifications. Na 2.x, o componente representa a superfície de notificação; o conteúdo deve ser composto por slots e subcomponentes.

Propriedades e composição

API 1.x	API 2.x	Ação na migração
disableCloseButton	—	Remova; use a composição de fechamento disponível.
notifications	—	Remova o objeto de dados e renderize os itens no conteúdo atual.
showNotification	open	Controle a abertura com a propriedade atual.
subtitle	conteúdo do slot	Mova o texto para a composição interna.
title	label ou slot	Use label para o gatilho/superfície e slot para conteúdo rico.
evento close	métodos/eventos de fechamento atuais	Atualize o listener conforme o fluxo da aplicação.

Exemplo

1.x:

<br-notification :notifications="notifications" show-notification></br-notification>

2.x:

<br-notification label="Notificações" open>
  <div slot="content">Itens da notificação</div>
</br-notification>