Shadow DOM web components: o que é e como usar

Shadow DOM é uma árvore DOM encapsulada que se anexa a um elemento do DOM principal. Ela isola estilos e marcação, permitindo criar web components reutilizáveis sem que o CSS de fora interfira no de dentro. O ponto de entrada é o método attachShadow().

O que é shadow DOM em web components?

Shadow DOM é uma API que permite criar uma subárvore DOM separada dentro de um elemento. Essa subárvore tem seu próprio escopo de estilos e não é acessível por seletores CSS externos. Na prática, você define um elemento e anexa um shadow root a ele. Todo o conteúdo dentro desse root fica protegido.

A ideia central é encapsulamento. Sem shadow DOM, um seletor global como div { color: red } afetaria qualquer div dentro do componente. Com shadow DOM, o estilo externo não atravessa a fronteira do shadow root.

Como criar um shadow root na prática?

O processo tem três passos: criar um elemento, anexar o shadow root e preencher o conteúdo. Veja um exemplo mínimo:

const host = document.createElement('div'); const shadow = host.attachShadow({ mode: 'open' }); shadow.innerHTML = '<style>p { color: blue; }</style><p>Olá, shadow DOM!</p>'; document.body.appendChild(host);

O parâmetro mode aceita 'open' ou 'closed'. Com 'open', o shadow root é acessível via host.shadowRoot. Com 'closed', ele fica inacessível por essa propriedade. A maioria dos casos de uso adota 'open' para facilitar depuração.

Por que o CSS não vaza para fora do shadow DOM?

O shadow DOM cria uma fronteira de estilo. Regras definidas fora do shadow root não afetam os elementos internos, e regras internas não afetam o resto da página. Isso resolve um problema clássico de componentes de terceiros: o estilo global quebrar o layout do widget.

Existem exceções. Propriedades herdáveis como color e font-family ainda passam pela fronteira. Para controle total, use :host e variáveis CSS customizadas.

Shadow DOM e custom elements andam juntos?

Sim. Custom elements definem a tag personalizada, e o shadow DOM define o que ela renderiza internamente. A combinação dos dois, mais templates HTML, forma a base dos web components nativos. Frameworks como Lit encapsulam essa lógica, mas o funcionamento por baixo é o mesmo.

Resumo rápido

Shadow DOM isola marcação e estilo dentro de um componente. Use attachShadow() para criar o root, mode: 'open' para depurar com facilidade, e :host para estilizar o próprio componente a partir de fora.

FAQ

O shadow DOM substitui o DOM normal?

Não. O shadow DOM é anexado a um elemento do DOM principal, chamado host. Os dois coexistem. O DOM principal continua acessível por JavaScript e CSS, enquanto o shadow root fica isolado.

Qual a diferença entre shadow DOM aberto e fechado?

No modo aberto, o shadow root é acessível via element.shadowRoot. No modo fechado, essa propriedade retorna null. O modo fechado dificulta inspeção e testes, por isso o aberto é mais comum.

Posso usar shadow DOM fora de web components?

Sim. Você pode anexar um shadow root a qualquer elemento HTML, como uma div. Web components são o caso de uso mais frequente, mas não o único.

Como estilizar elementos dentro do shadow DOM?

Use a tag <style> dentro do próprio shadow root ou adote adoptedStyleSheets. Seletores externos não alcançam o interior, exceto propriedades herdáveis e variáveis CSS.

O shadow DOM afeta a acessibilidade?

O conteúdo dentro do shadow root é acessível a leitores de tela quando o host tem o papel semântico adequado. Evite usar shadow DOM para esconder conteúdo que deveria ser lido por tecnologias assistivas.