Modal

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-modal é a caixa de diálogo bloqueadora (dialog modal) do GovBR-DS, desenvolvida para capturar o foco e exigir a atenção imediata da pessoa usuária antes de permitir o retorno ao fluxo de trabalho normal.

Para que serve

• Confirmação de ações críticas: Solicita confirmação explícita para ações irreversíveis ou de grande impacto (ex.: excluir registro, cancelar processo em andamento).
• Entrada de dados pontual: Permite preencher formulários breves e contextuais sem sair da tela principal.
• Gestão de foco e acessibilidade WAI-ARIA: Bloqueia o foco dentro do diálogo (focus trap), impede a rolagem do fundo, aplica aria-modal="true" e fecha com a tecla Escape ou clique externo.

Quando utilizar

• Utilize quando:
  • A decisão for estritamente obrigatória e a continuação sem ela puder causar perda de dados ou inconsistência.
  • Apresentar detalhes suplementares que requerem fechamento explícito.
• Evite e prefira outro componente quando:
  • A mensagem for informativa e não exigir ação imediata (prefira br-message).
  • O conteúdo for extenso, demandando navegação complexa (prefira uma nova página dedicada).

Estrutura e Slots

O br-modal organiza o diálogo em regiões padronizadas:

• header: Slot para cabeçalho e título (substitui a prop title-text).
• default: Slot principal onde é inserido o corpo de texto ou formulário do modal.
• footer: Slot para ações de rodapé (botões de confirmação, envio e cancelamento com br-button).
• close-button: Slot para personalizar o botão de fechar do canto superior.

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

Composição com scrim

O modal continua sendo o conteúdo do br-scrim e preserva open(), showModal(), close(), eventos, foco e slots. Quando o scrim fullscreen usa <dialog>, o conjunto entra na top layer; em ambientes sem showModal(), usa a camada bloqueadora 4 e o gerenciamento de foco legado.

A ordem de abertura define a precedência entre diálogos nativos: o último bloqueador aberto fica ativo. No fallback CSS, mantenha apenas um bloqueador legado ativo por vez.

Propriedades

alignFooter

Atributo	align-footer
Descrição	Define o alinhamento do conteúdo do rodapé (slot="footer"). Valores inválidos usam center.
Tipo	"center" | "end" | "start"
Valor padrão	'center'

autoClose

Atributo	auto-close
Descrição	Define o comportamento de fechamento do modal. - true: O modal fecha automaticamente ao clicar no botão fechar. - false: O modal emite brModalBeforeClose mas não fecha, permitindo a implementação de lógica customizada (validação, confirmação, etc.) antes do fechamento. O desenvolvedor deve controlar manualmente o fechamento.
Tipo	boolean
Valor padrão	false

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()

initialFocusSelector

Atributo	initial-focus-selector
Descrição	Seletor CSS do elemento que deve receber foco quando o modal é aberto (ex: "#meu-elemento").
Tipo	string
Valor padrão	---

scrollable

Atributo	scrollable
Descrição	Se true, habilita a rolagem interna do conteúdo do modal.
Tipo	boolean
Valor padrão	false

show

Atributo	show
Descrição	Controla a visibilidade do modal.
Tipo	boolean
Valor padrão	false

size

Atributo	size
Descrição	Define o tamanho (largura) do modal. Valores inválidos usam medium.
Tipo	"auto" | "large" | "medium" | "small" | "xsmall"
Valor padrão	'medium'

titleText

Atributo	title-text
Descrição	O texto do título a ser exibido no cabeçalho do modal. Usado quando o slot header não é fornecido.
Tipo	string
Valor padrão	---

Slots

Nome	Descrição
"close-button"	Botão de fechar customizado. Se não for usado, o botão padrão será exibido.
"default"	Corpo do modal.
"footer"	Rodapé do modal.
"header"	Cabeçalho do modal. Se não for usado, o title-text será exibido.

Eventos

Evento	Descrição	Depreciação	Propagação
brModalBeforeClose	Evento emitido antes do fechamento do modal (quando o botão X é clicado). Se autoClose está desativado, o desenvolvedor deve fechar manualmente o modal após este evento. Se autoClose está ativado, o modal fecha automaticamente após este evento.	---	true
brModalClose	Evento emitido após o modal ser fechado (quando show muda de true para false).	---	true
brModalOpen	Evento emitido quando o modal é aberto (quando show muda de false para true).	---	true
brModalOpened	Evento emitido após o modal estar completamente aberto e com o foco estabilizado dentro dele. Complementa brModalOpen (que dispara imediatamente ao abrir): use brModalOpened quando precisar interagir com o modal já pronto.	---	true

Métodos

close

Descrição	Método público para fechar o modal
Assinatura	close() => Promise<void>
Parâmetros	---

open

Descrição	Método público para abrir o modal
Assinatura	open() => Promise<void>
Parâmetros	---

requestClose

Descrição	Solicita fechamento e permite cancelamento pelo evento cancel.
Assinatura	requestClose() => Promise<void>
Parâmetros	---

showModal

Descrição	Abre o modal usando a nomenclatura de HTMLDialogElement.
Assinatura	showModal() => Promise<void>
Parâmetros	---

toggle

Descrição	Método público para alternar a visibilidade do modal
Assinatura	toggle() => Promise<void>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"body"	Corpo do modal.
"close-button"	Botão de fechar do modal.
"container"	Wrapper principal do modal.
"footer"	Rodapé do modal.
"header"	Cabeçalho do modal.
"title"	Título do modal.

Acessibilidade

O br-modal é um diálogo bloqueador. Quando aberto usa <dialog> nativo (ou role="dialog" no fallback) com aria-modal="true", tabindex="-1", aria-labelledby apontando para o título (title-text ou o slot header) e aria-describedby apontando para o corpo.

Foco

• Ao abrir, o foco vai para o elemento indicado por initial-focus-selector ou, na ausência dele, para o próprio contêiner do modal.
• O foco fica preso no diálogo: Tab e Shift+Tab circulam entre os elementos focáveis internos (o trap usa o primeiro/último focável real, inclusive dentro de Shadow DOM).
• Ao fechar, o foco volta para o elemento que abriu o modal.
• A rolagem do conteúdo de fundo fica bloqueada enquanto o modal está aberto.

Teclado

• Escape fecha o modal (a menos que brModalBeforeClose seja cancelado).
• Clique fora da área do diálogo fecha quando auto-close está ativo.

Conteúdo

Use o slot header (ou title-text) para um título significativo — ele vira o nome acessível. O botão de fechar tem rótulo próprio; ao customizá-lo pelo slot close-button, mantenha um nome acessível ("Fechar").

Movimento

As transições de entrada e saída respeitam prefers-reduced-motion: reduce.

Eventos nativos

Elemento HTML de referência

A referência é <dialog>. O modal independente usa esse elemento e a top layer; dentro de br-scrim, o componente preserva um contêiner com role="dialog" para que exista apenas um owner da sobreposição.

Como ouvir os eventos

const modal = document.querySelector('br-modal');

modal.addEventListener('cancel', (event) => {
  event.preventDefault();
});

Eventos nativos suportados

Evento	Quando ocorre	Bubbles	Composed	Cancelable	Host	Observações
cancel	componente recebe pedido de fechamento	Não	Não	Sim	Sim	Normalizado no host; cancelar mantém o modal aberto.
close	fechamento termina	Não	Não	Não	Sim	Normalizado uma vez no host e sem returnValue.

Eventos não aplicáveis ou não suportados

Evento	Situação	Motivo	Alternativa
beforetoggle / toggle	Não suportado	Não há modo não modal no contrato.	Observe show e os eventos documentados.
returnValue	Não suportado	O contrato não define resultado de diálogo.	Transporte dados na aplicação antes de fechar.

Eventos customizados do componente

Evento	Quando ocorre	Detail	Bubbles	Composed	Cancelable
brModalBeforeClose	antes do pedido de fechamento	nenhum	legado	legado	legado
brModalClose	ciclo legado de fechamento	nenhum	legado	legado	legado
brModalOpen / brModalOpened	abertura solicitada/concluída	nenhum	conforme declaração	conforme declaração	Não

Valor e estado após o evento

Leia show no host. Os eventos cancel e close não transformam o componente em HTMLDialogElement.

Frameworks

Registre cancel/close diretamente no host em HTML, React por ref, Angular e Vue com seus listeners DOM. Eventos brModal* continuam separados.

Acessibilidade

O componente gerencia foco e Escape, mas a equivalência completa com modal nativo depende dos testes de foco, inertização e restauração documentados no componente.

Evidência de teste

_tests/modal.e2e.tsx cobre standalone, composição com scrim, cancelamento, fechamento único e ARIA em Chromium headless. A matriz completa em três engines permanece pendente.

Atributos nativos

Quando independente, br-modal renderiza <dialog> e usa showModal() para entrar na top layer. Dentro de br-scrim, mantém <div role="dialog"> para que o scrim continue proprietário da sobreposição.

O estado público continua em show; os métodos são open(), showModal(), close() e requestClose(). returnValue, show() não modal, beforetoggle e toggle nativo não são suportados porque não há resultado nem modo não modal no contrato atual.

Dependências

Depende de

• br-button
• br-icon

Gráfico

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

O modal continua sendo controlado por show, mas títulos, rodapé e dimensionamento foram reorganizados.

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
buttons	slot footer	Mova os botões para o rodapé.
centerButtons	alignFooter	Renomeie e revise os valores.
closable	slot close-button	Remova a flag e personalize o botão, se necessário.
close-modal	brModalClose	Atualize o listener.
maxHeight	scrollable	Troque o limite fixo pelo comportamento de rolagem.
show	show	Mantenha.
title	titleText ou slot header	Renomeie ou mova para o slot quando houver marcação customizada.
width	size	Converta para o tamanho disponível.

Exemplo

1.x:

<br-modal title="Confirmação" width="large" center-buttons>
  <template #buttons><br-button>OK</br-button></template>
</br-modal>

2.x:

<br-modal title-text="Confirmação" size="large" align-footer="center">
  <div slot="footer"><br-button>OK</br-button></div>
</br-modal>