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 br-scrim cria uma máscara visual escura sobre a tela ou sobre um elemento pai para focar a atenção do usuário.

Use os métodos show(), hide() ou a propriedade active para controlar a exibição. Coloque o conteúdo em destaque no slot padrão.

<br-scrim active>
  <div class="destaque">Conteúdo em evidência</div>
</br-scrim>

Quando usar

Destaque visual pontual de um elemento (tutoriais guiados ou máscaras personalizadas).

Quando evitar

Caixas de diálogo modais padrão: use br-modal (que já gerencia seu próprio scrim internamente).

Consulte as diretrizes de design do GovBR.

Exemplos

Carregando preview…

Recolher controles e código

Sobreposição e contexto

Na variante fullscreen (padrão em focus e spotlight), o scrim cria uma máscara em tela cheia que bloqueia interações com a página. Quando suportado pelo navegador, utiliza <dialog> e a top layer, evitando que estilos de elementos ancestrais interfiram na exibição.

Nas variantes parent e legibility, o scrim restringe a máscara visual ao elemento pai relativo.

Teclado e foco

Quando o scrim está ativo e seu conteúdo gerencia o layout padrão, ele contém o foco no conteúdo: Tab e Shift+Tab percorrem os elementos habilitados e visíveis e envolvem do último para o primeiro ou do primeiro para o último. Se o conteúdo não tiver controles focalizáveis, Tab não move o foco para fora do scrim. O foco que tentar sair da superfície é direcionado de volta para o conteúdo.

Escape fecha o scrim quando ele está ativo. Se houver uma modal filha com fechamento automático, ela tem a oportunidade de tratar Escape primeiro.

Com content-layout="none", o scrim não intercepta foco nem eventos globais; o componente filho passa a gerenciar seu próprio foco, teclado e fechamento. Quando o navegador oferece suporte, a variante fullscreen pode usar <dialog> e a top layer. O scrim restaura o foco ao elemento que o ativou ao fechar.

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​

Quando usar​

Quando evitar​

Sobreposição e contexto​

Teclado e foco​

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​