Copiar página como Markdown para IA

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

O componente br-scrim é a camada de sobreposição visual (backdrop / máscara) do GovBR-DS, utilizada para escurecer temporariamente a interface e direcionar a atenção da pessoa usuária para um ponto de interesse ou diálogo.

Para que serve

Destaque visual exclusivo (Spotlight): Cria um foco exclusivo sobre determinado elemento da página (como um tour guiado ou tutorial introdutório).
Bloqueio de interação com o fundo: Impede cliques acidentais e rolagem na interface subjacente enquanto uma superfície flutuante estiver ativa.
Comportamento acessível de fechamento: Suporta fechamento ao clicar na máscara ou ao pressionar a tecla Escape, com controle de foco previsível.

Quando utilizar

Utilize quando:
- For necessário criar máscaras de fundo personalizadas para fluxos de onboarding, tutoriais ou menus temporários imersivos.
Evite e prefira outro componente quando:
- Estiver implementando uma caixa de diálogo padrão com cabeçalho, corpo e rodapé (prefira br-modal, que já inclui seu próprio scrim interno).

Estrutura e Slots

O br-scrim atua como superfície de sobreposição:

default: Slot para inserção do elemento que receberá o destaque em primeiro plano sobre a máscara.

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

Exemplo(s)

Padrão

Spotlight

Legibilidade

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Tela cheia

Carregando preview…

Recolher controles e código

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.
Exemplo de uso	`<button id="abrir-ajuda" type="button">Abrir ajuda</button> <br-scrim activator="#abrir-ajuda">Conteúdo</br-scrim>`
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. O valor é limitado ao intervalo `0`–`1`; entradas inválidas usam `0.4`.
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.
Exemplo de uso	`<br-scrim variant="legibility" legibility-anchor="bottom" legibility-size="40%"> Texto sobre a imagem </br-scrim>`
Tipo	`string`
Valor padrão	`null`

legibilityTargetId

Atributo	`legibility-target-id`
Descrição	Seletor CSS do elemento que deve receber o posicionamento da variante `legibility`. Quando não informado (padrão), o alvo é o elemento pai direto do `<br-scrim>`.
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. Valores negativos usam `0`.
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. Valores negativos usam `0`.
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.
Exemplo de uso	`<button id="acao-principal" type="button">Continuar</button> <br-scrim variant="spotlight" spotlight-target-id="#acao-principal"></br-scrim>`
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. Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.
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>

Visão Geral​

Para que serve​

Quando utilizar​

Estrutura e Slots​

Exemplo(s)​

Fluxo, camada e top layer​

Propriedades​

activator​

ariaLabel​

bgColor​

contentLayout​

customId​

customOpacity​

disableCloseOnClick​

displayMode​

isOpen​

legibilityAnchor​

legibilitySize​

legibilityTargetId​

positionContent​

scrollStrategy​

scrollThreshold​

spotlightPadding​

spotlightShape​

spotlightTargetId​

variant​

zIndex​

Slots​

Eventos​

Métodos​

close​

open​

setScrollThreshold​

toggle​

updateSpotlight​

Dependências​

Usado por​

Gráfico​

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

Propriedades e eventos​

Exemplo​