by JimDabell | 2025-06-28 15:24:43+00:00
Let’s take this example:

<!DOCTYPE html> <title>Example</title> <cool-dog> <template shadowrootmode="open"> <style> :host { display: block; font-family: system-ui; margin: auto; width: fit-content; } ::slotted(img) { border-radius: 1em; } </style> <slot></slot> </template> <img src="https://placedog.net/512/342?random" width="512" height="342" alt="A dog" > <p>Check out this cool dog!</p> </cool-dog> <script> customElements.define( "cool-dog", class extends HTMLElement {}, ); </script>

First off, what’s with the pointless JavaScript? There’s no need for imperative code here. All web components have a dash in the name; this can be inferred. But even if you want it to be explicit, this could be done with markup not imperative code. But no, it doesn’t work without the pointless JavaScript ritual.

Now, I’ve noticed that since the text is a caption for the image, I should actually use <figure> and <figcaption>. So let’s do that:

<!DOCTYPE html> <title>Example</title> <cool-dog> <template shadowrootmode="open"> <style> :host { display: block; font-family: system-ui; margin: auto; width: fit-content; } ::slotted(img) { border-radius: 1em; } </style> <slot></slot> </template> <figure> <img src="https://placedog.net/512/342?random" width="512" height="342" alt="A dog" > <figcaption>Check out this cool dog!</figcaption> </figure> </cool-dog> <script> customElements.define( "cool-dog", class extends HTMLElement {}, ); </script>

Wait a sec! The nice round corners on the image have turned into ugly square ones. Why is that?

It’s because web components can’t style anything other than their direct children. You can style the <img> when it’s a direct child of the web component, but as soon as you need anything more complex than an entirely flat hierarchy, you run into problems. Even if it’s something as simple as wrapping an <img> in a <figure> to associate it with a <figcaption>.

What’s the “official” way of getting things like this done when you bring it up with the people working on the specs? Make a custom property to fake the real one and then set a global style that listens to the fake property to set it on the real one:

<!DOCTYPE html> <title>Example</title> <style> img { border-radius: var(--border-radius); } </style> <cool-dog> <template shadowrootmode="open"> <style> :host { display: block; font-family: system-ui; margin: auto; width: fit-content; --border-radius: 1em; } </style> <slot></slot> </template> <figure> <img src="https://placedog.net/512/342?random" width="512" height="342" alt="A dog" > <figcaption>Check out this cool dog!</figcaption> </figure> </cool-dog> <script> customElements.define( "cool-dog", class extends HTMLElement {}, ); </script>

Now let’s say I want to put a second <cool-dog> element on the page. What does that look like? You define the template once and then just use <cool-dog> a bunch of times? That would be the obvious thing to do, right? Since it’s a template?

Nope. Every instance of the web component needs its own <template>. The best you can do is write some JavaScript to copy the template into each one.

The developer ergonomics of this stuff is terrible. It’s full of weird limitations and footguns.