Estilizando Web Components con Shadow DOM y CSS

Si alguna vez has colocado un Web Component en una página y te has preguntado por qué tu CSS global dejó de funcionar dentro de él, te has topado con la frontera del shadow. No es un error — es precisamente el propósito. El Shadow DOM otorga a los elementos personalizados su propio árbol DOM con alcance aislado, lo que significa que los estilos no se filtran ni hacia adentro ni hacia afuera por defecto. Pero eso no significa que sea imposible aplicar estilos. Significa que aplicar estilos es intencional.

Este artículo cubre los principales mecanismos para estilizar el Shadow DOM: estilos internos, :host, ::slotted(), propiedades personalizadas de CSS, ::part() y adoptedStyleSheets.

Por qué el Shadow DOM cambia el comportamiento del CSS

Cuando llamas a attachShadow() sobre un elemento, creas un árbol DOM independiente adjunto a ese elemento (el shadow host). Los selectores de la hoja de estilos de tu página no pueden alcanzar el interior de ese árbol, y los selectores dentro del shadow tree no pueden alcanzar el exterior.

Hay un matiz importante que conviene entender: los estilos del Shadow DOM se sitúan por debajo de tus estilos definidos en la cascada CSS. Eso significa que una regla global como * { color: red } sobrescribirá una regla :host { color: green } dentro del shadow — incluso si la regla global aparece antes en el orden del código fuente. Piensa en los estilos del shadow como los estilos por defecto del componente, de manera similar a cómo la hoja de estilos user-agent del navegador provee valores por defecto para <button> o <input>.

Estilizando el Shadow Host con :host

Desde dentro del shadow tree, :host selecciona el elemento al que está adjunto el shadow:

:host {
  display: block;
  font-family: sans-serif;
}

También puedes usar :host(selector) para aplicar estilos condicionalmente según los atributos o clases del host:

:host([disabled]) {
  opacity: 0.5;
  pointer-events: none;
}

Como el elemento host vive en el light DOM, los estilos a nivel de documento sobrescribirán las reglas :host. Si quieres que los valores por defecto del componente prevalezcan, recurre a !important dentro del shadow — uno de los pocos casos en los que su uso es genuinamente apropiado.

Estilizando contenido proyectado con ::slotted()

Los slots permiten proyectar contenido del light DOM dentro de un shadow tree. El pseudo-elemento ::slotted() permite estilizar esos elementos proyectados desde dentro del shadow:

::slotted(p) {
  margin: 0;
  color: #333;
}

Limitación importante: ::slotted() solo coincide con el elemento asignado directamente a un slot — no con sus descendientes. Un selector como ::slotted(p span) no funcionará, y ::slotted() solo acepta un selector compuesto (sin combinadores de descendencia). Para un estilizado más profundo, apóyate en la herencia de CSS o deja que los propios estilos del light DOM se encarguen.

Las propiedades personalizadas de CSS cruzan la frontera del shadow

Las variables CSS (propiedades personalizadas) atraviesan libremente la frontera del shadow. Esto las convierte en la herramienta más flexible para el theming de Web Components:

/* En el shadow tree */
:host {
  background: var(--card-bg, white);
  color: var(--card-color, black);
}

/* En la hoja de estilos de tu página */
my-card {
  --card-bg: #1a1a2e;
  --card-color: #eee;
}

El componente define los puntos de enganche; el consumidor establece los valores. Incluye siempre valores de respaldo para que el componente funcione sin ninguna configuración externa.

Exponiendo puntos de estilizado con CSS Shadow Parts (::part())

CSS Shadow Parts son la respuesta moderna para estilizar elementos internos de un Web Component desde fuera. Dentro del componente, marcas los elementos con el atributo part:

<button part="trigger">Open</button>

Fuera del componente, los consumidores pueden apuntar directamente a esa parte usando ::part():

my-dialog::part(trigger) {
  background: royalblue;
  border-radius: 4px;
}

Esta es una API de estilizado intencional — el autor del componente decide qué se expone. Es más potente que las variables CSS para el estilizado estructural (layout, bordes, fondos) a la vez que mantiene los detalles de implementación interna privados.

Compartiendo estilos eficientemente con adoptedStyleSheets

adoptedStyleSheets te permite adjuntar objetos CSSStyleSheet directamente a un shadow root. Tiene un amplio soporte en los navegadores modernos y es muy adecuado para bibliotecas de componentes que necesitan compartir una hoja de estilos parseada entre muchas instancias:

const sheet = new CSSStyleSheet();
sheet.replaceSync(`:host { display: block; }`);

class MyComponent extends HTMLElement {
  constructor() {
    super();
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.adoptedStyleSheets = [sheet];
  }
}

customElements.define('my-component', MyComponent);

El navegador parsea la hoja de estilos una sola vez, sin importar cuántos componentes la usen — una ganancia de rendimiento significativa a escala. Puedes añadir o eliminar hojas de estilos mutando el array adoptedStyleSheets, y los cambios en un CSSStyleSheet compartido se aplican en todos los lugares donde está adoptado.

Eligiendo el enfoque adecuado

Conclusión

Estilizar con Shadow DOM no se trata de bloquear el CSS — se trata de hacer explícita la encapsulación. Usa estilos internos y :host para los valores por defecto, variables CSS y ::part() como tu API pública de estilizado, y adoptedStyleSheets cuando el rendimiento a escala importa. Una vez que tengas ese modelo mental, estilizar Web Components se vuelve sencillo.

Preguntas frecuentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.