::slotted(): Style Content Passed into Web Components

Why it exists

Web Components encapsulate their structure and styles in a shadow DOM, which is normally a black box. But components often need to render content provided by the user via slots. ::slotted() was created to bridge this gap, allowing the component author to style that user-provided content without breaking encapsulation.

The mental model

Think of ::slotted() as a component's way of styling its inputs. When you pass an element into a component's <slot>, that element lives in the "light DOM" but is rendered by the component. ::slotted() is the CSS selector that lets the component's internal stylesheet (in the shadow DOM) target and style that specific light DOM element. It's a controlled way to cross the shadow DOM boundary for styling purposes.

How it works

You use ::slotted() inside a <style> tag within a component's shadow DOM. The selector takes an argument that specifies which slotted elements to target. For example, ::slotted(p.content) selects any element with a class of 'content' that has been placed into any <slot> in that component's template. The styles are then applied to that element as it's rendered. It only works on elements, not on text nodes directly placed in a slot.

When to use it

Use ::slotted() when you are building a Web Component and need to enforce a consistent look and feel for the content that users will provide. It's perfect for styling slotted headings, paragraphs, or icons to match the component's theme, without forcing the user to know the internal class names.

When not to use it

Do not try to use ::slotted() in a global stylesheet; it has no effect outside of a shadow DOM. Avoid it if you want the user to have complete control over the styling of the content they provide. Also, remember it doesn't work for text nodes, so if you need to style text, make sure it's wrapped in an element like a .

One canonical example

A <custom-card> component defines a shadow DOM with a slot: <slot name="caption"></slot>. Inside its shadow CSS, it has ::slotted([slot="caption"]) { font-weight: bold; }. When a user writes <custom-card><h2 slot="caption">My Title</h2></custom-card>, the <h2> is rendered in bold, styled by the component itself, even though the <h2> was defined outside the component.