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

Para a documentação completa, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Compartilhar URL

Mudar fundo

Abrir no StackBlitz

Tela cheia

HTML

Controles

JS

CSS

Console

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Formatar código

Resetar código para o estado inicial

Copiar para a área de transferência

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").
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.
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.

Dependências

Depende de

• br-button
• br-icon

Gráfico

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.

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>