Scrim

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

Design System

Para a documentação completa de design, 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

Fluxo, camada e top layer

O scrim fullscreen das variantes focus e spotlight, com layout de conteúdo padrão, usa <dialog> modal e showModal(). Isso evita limitações impostas por ancestrais com transform, filter ou outros stacking contexts. Sem suporte nativo, permanece fixed na camada bloqueadora 4.

As variantes parent e legibility, além de content-layout="none", continuam locais. Em todas as composições a máscara ocupa a subcamada 0 e o conteúdo a 1. No fallback CSS, mantenha somente um bloqueador legado ativo por vez.

Propriedades

activator

Atributo	activator
Descrição	Define o seletor para o elemento activator. Nota: O slot 'activator' tem prioridade sobre esta propriedade.
Tipo	string
Valor padrão	null

ariaLabel

Atributo	aria-label
Descrição	Define um rótulo acessível personalizado para o diálogo. Se não fornecido, será usado "Conteúdo do diálogo" como padrão.
Tipo	string
Valor padrão	null

bgColor

Atributo	bg-color
Descrição	Cor de fundo personalizada para o scrim. Aceita os seguintes formatos de cor: - Cores nomeadas do CSS: 'red', 'blue', 'green', 'yellow', etc. - Códigos hexadecimais: '#ff0000', '#00ff00', '#0000ff', etc. - Valores RGB: 'rgb(255, 0, 0)', 'rgb(0, 255, 0)', etc. - Valores RGBA: 'rgba(255, 0, 0, 0.5)', 'rgba(0, 255, 0, 0.8)', etc. - Valores HSL: 'hsl(0, 100%, 50%)', 'hsl(120, 100%, 50%)', etc. - Valores HSLA: 'hsla(0, 100%, 50%, 0.5)', 'hsla(240, 100%, 50%, 0.7)', etc. Se não especificada, usa a cor padrão do tema.
Tipo	string
Valor padrão	null

contentLayout

Atributo	content-layout
Descrição	Define como o scrim aplica estilos de layout ao elemento filho (slot padrão). - 'default': O scrim gerencia o layout do conteúdo, centralizando, animando e aplicando transformações e opacidade automaticamente. - 'none': o scrim age como um componente controlado pelo pai. O filho recebe apenas a máscara visual, sem interferência de posicionamento, transformação ou opacidade. Adequado para componentes que gerenciam seu próprio layout e estado de abertura. Além disso: - Foco e eventos globais** não são interceptados pelo scrim — o componente filho gerencia seu próprio foco, navegação por teclado e fechamento via ESC. - Clique no scrim emite brScrimClose sem fechar o scrim internamente, delegando o controle de estado ao pai (quem define isOpen). - Use zIndex apenas para sobrescrever a camada bloqueadora no fallback CSS. Máscara e painel devem usar subcamadas locais, sem aritmética entre camadas globais.
Tipo	"default" | "none"
Valor padrão	'default'

customId

Atributo	custom-id
Descrição	Identificador único. Caso não seja fornecido, um ID gerado automaticamente será usado.
Tipo	string
Valor padrão	generateUniqueId()

customOpacity

Atributo	custom-opacity
Descrição	Define a opacidade personalizada do scrim
Tipo	number
Valor padrão	null

disableCloseOnClick

Atributo	disable-close-on-click
Descrição	Desativa o fechamento do scrim ao ser clicado
Tipo	boolean
Valor padrão	false

displayMode

Atributo	display-mode
Descrição	Define o modo de exibição do scrim: - 'fullscreen': Ocupa toda a tela (position: fixed). (padrão) - 'parent': Ocupa apenas o elemento pai (position: absolute). O elemento pai deve ter position: relative ou outro valor diferente de static. Para a variante 'legibility', este atributo é ignorado: o posicionamento é sempre calculado automaticamente a partir das coordenadas do elemento pai.
Tipo	"fullscreen" | "parent"
Valor padrão	'fullscreen'

isOpen

Atributo	is-open
Descrição	Ativa/desativa o scrim
Tipo	boolean
Valor padrão	false

legibilityAnchor

Atributo	legibility-anchor
Descrição	Define a borda de ancoragem da faixa de cobertura da variante legibility. Controla de qual borda (ou centro) do elemento a máscara de overlay cresce, tendo seu tamanho determinado por legibilitySize. - 'top': faixa ancorada na borda superior, cresce para baixo. - 'bottom': faixa ancorada na borda inferior, cresce para cima. - 'left': faixa ancorada na borda esquerda, cresce para a direita. - 'right': faixa ancorada na borda direita, cresce para a esquerda. - 'center': faixa centralizada verticalmente no elemento. Quando legibilitySize é null, a máscara ocupa 100% independentemente da âncora definida, equivalendo a uma cobertura total. Só tem efeito quando variant="legibility".
Tipo	"bottom" | "center" | "left" | "right" | "top"
Valor padrão	'bottom'

legibilitySize

Atributo	legibility-size
Descrição	Define o tamanho da faixa de cobertura da variante legibility, usado em conjunto com legibilityAnchor. Aceita qualquer valor CSS de comprimento válido: - Percentual relativo ao elemento pai: '40%', '75%' - Comprimento absoluto: '120px', '8rem', '6em' - Função CSS: 'calc(100% - 2rem)' Quando null (padrão), a máscara ocupa 100% da dimensão relevante: - altura para âncoras top, bottom e center - largura para âncoras left e right Só tem efeito quando variant="legibility" está definido.
Tipo	string
Valor padrão	null

positionContent

Atributo	position-content
Descrição	Posiciona o conteúdo no topo, centro, direita, esquerda, abaixo dentro do scrim (obrigatório)
Tipo	"bottom" | "center" | "left" | "right" | "top"
Valor padrão	---

scrollStrategy

Atributo	scroll-strategy
Descrição	Define a estratégia de manipulação de rolagem quando scrim está aberto - 'block': Impede a rolagem completamente - 'close': Fecha o scrim quando ocorre rolagem (obrigatório)
Tipo	"block" | "close"
Valor padrão	---

scrollThreshold

Atributo	scroll-threshold
Descrição	Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim.
Tipo	number
Valor padrão	50

spotlightPadding

Atributo	spotlight-padding
Descrição	Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado.
Tipo	number
Valor padrão	8

spotlightShape

Atributo	spotlight-shape
Descrição	Define a forma da área de fresta no scrim vazado. - 'rect': Retangular com bordas retas. - 'rounded': Retangular com bordas arredondadas (border-radius de 8px). - 'circle': Elipse inscrita na área do elemento alvo.
Tipo	"circle" | "rect" | "rounded"
Valor padrão	'rect'

spotlightTargetId

Atributo	spotlight-target-id
Descrição	Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlay que destaca o elemento referenciado pelo seletor CSS fornecido.
Tipo	string
Valor padrão	null

variant

Atributo	variant
Descrição	Define a variante semântica do scrim - 'focus': Redireciona o foco hierárquico do usuário. Cor #000000 com opacidade 40%. (padrão) - 'spotlight': Scrim vazado — destaca um elemento específico criando uma fresta no overlay. Aplica as mesmas cores da variante 'focus'. Use spotlightTargetId para indicar o elemento a ser destacado. - 'legibility': Melhora o contraste e leitura de texto sobre superfícies. Cor #000000 com opacidade 64%. Para cobertura parcial, use legibilityAnchor + legibilitySize. Para gradiente suave, use bgColor com um valor de gradiente CSS e customOpacity="1", ex.: bg-color="linear-gradient(to top, rgba(0,0,0,0.64), transparent)".. Quando definida, aplica automaticamente as especificações de cor e opacidade do Design System. As propriedades bgColor e customOpacity têm prioridade e sobrepõem os valores da variante.
Tipo	"focus" | "legibility" | "spotlight"
Valor padrão	'focus'

zIndex

Atributo	z-index
Descrição	Define o valor de z-index do scrim
Tipo	number
Valor padrão	null

Slots

Nome	Descrição
"activator"	Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator.
"default"	Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.

Eventos

Evento	Descrição	Depreciação	Propagação
brScrimClose	Indica que o scrim foi fechado	---	true
brScrimOpen	Indica que o scrim foi aberto.	---	true

Métodos

close

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

open

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

setScrollThreshold

Descrição	Define o limite de rolagem para o fechamento automático do scrim.
Assinatura	setScrollThreshold(threshold: number) => Promise<void>
Parâmetros	threshold:

toggle

Descrição	Método público para alternar o estado de exibição do scrim
Assinatura	toggle() => Promise<void>
Parâmetros	---

updateSpotlight

Descrição	Recalcula manualmente a posição e dimensões da fresta do scrim vazado. Útil quando o elemento alvo muda de posição sem disparar resize ou scroll.
Assinatura	updateSpotlight() => Promise<void>
Parâmetros	---

Dependências

Usado por

• br-menu

Gráfico

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

O scrim mantém a função de camada de bloqueio, mas o estado atual usa isOpen e a posição do conteúdo é configurada explicitamente.

Propriedades e eventos

API 1.x	API 2.x	Ação na migração
autofocusContent	—	Remova e trate foco no conteúdo atual.
centerContent	positionContent	Converta para a posição desejada.
disableCloseOnClick	disableCloseOnClick	Mantenha.
id	customId	Renomeie a propriedade de identificação.
show	isOpen	Renomeie.
update:show / hide	brScrimOpen / brScrimClose	Atualize os listeners.

Use os slots de conteúdo e ativador para manter a relação semântica entre o elemento que abre o scrim e a camada exibida.

Exemplo

1.x:

<br-scrim show center-content></br-scrim>

2.x:

<br-scrim is-open position-content="center" disable-close-on-click></br-scrim>