Customized built-ins vs. autonomous elements
A customized built-in element is a standard HTML element that has been upgraded with custom behavior. The browser is told about the upgrade through an is attribute on the tag. The payoff is twofold: the element keeps its native formatting, parsing rules and built-in features, and assistive technology and search engines still recognize what it is. A screen reader has to guess at the purpose of an arbitrary <my-func> element, but it can infer something sensible from <nav is="my-func">.
Converting an autonomous element
The conversion is a small mechanical change. Instead of extending HTMLElement, extend the class of the element you're customizing — here, HTMLDivElement — and pass a third argument, {extends: 'div'}, to customElements.define.
customElements.define(
"apocalyptic-warning",
class ApocalypseWarning extends HTMLDivElement {
constructor() {
super();
let warning = document.getElementById("warningtemplate");
let mywarning = warning.content;
const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(
mywarning.cloneNode(true)
);
}
},
{ extends: "div" }
);
The markup changes from a bespoke tag to the native one carrying the attribute:
<div is="apocalyptic-warning">
<span slot="whats-coming">Undead</span>
</div>
Support caveat: Safari and a handful of more niche browsers implement autonomous elements only, so the customized built-in form does not run there.
Where a shadow root is allowed
Not every element can host a shadow root — attaching one to an <a> or <form>, for example, could carry security implications. The permitted set is largely layout elements: <article>, <section>, <aside>, <main>, <header>, <div>, <nav> and <footer>, plus text elements like <p>, <span>, <blockquote> and <h1>–<h6>. The body element and any valid autonomous custom element also qualify.
A shadow root is not a requirement, though. A web component is fundamentally a way to bake functionality into an element, and that functionality can live entirely in JavaScript.
Example: a light box built into <img>
Take a plain <img> and give it two attributes: is, marking it as a customized built-in, and a data attribute holding the path to the larger image to display in the light box. (With an SVG, the same URL serves both roles; a raster setup might use a small embedded image and a larger version for the overlay.)
<img is="light-box" src="https://assets.codepen.io/1804713/ninja2.svg" alt="Silent but Undeadly Zombie Ninja" />
Because <img> cannot take a shadow root, this component needs no <template>, no <slot> elements and no style encapsulation. The behavior is all in the script:
customElements.define(
"light-box",
class LightBox extends HTMLImageElement {
constructor() {
super();
// We’re creating a div element to use as the light box. We’ll eventually insert it just before the image in question.
let lb = document.createElement("div");
// Since we can’t use a shadow DOM, we can’t encapsulate our styles there. We could add these styles to the main CSS file, but they could bleed out if we do that, so I’m setting all styles for the light box div right here
lb.style.display = "none";
lb.style.position = "absolute";
lb.style.height = "100vh";
lb.style.width = "100vw";
lb.style.top = 0;
lb.style.left = 0;
lb.style.background =
"rgba(0,0,0, 0.7) url(" + this.dataset.lbsrc + ") no-repeat center";
lb.style.backgroundSize = "contain";
lb.addEventListener("click", function (evt) {
// We’ll close our light box by clicking on it
this.style.display = "none";
});
this.parentNode.insertBefore(lb, this); // This inserts the light box div right before the image
this.addEventListener("click", function (evt) {
// Opens the light box when the image is clicked.
lb.style.display = "block";
});
}
},
{ extends: "img" }
);
Bridging the Safari gap
WebComponents.org publishes a general polyfill covering both customized built-ins and autonomous elements. It may be far more than you need if only the former is missing on your support matrix. Since Safari does support autonomous elements, one narrower route is to swap the customized <img> for an autonomous <lightbox-polyfill> in that browser.
The light box code survives largely intact, with a small addition: a Boolean declared alongside the element definition.
let customBuiltInElementsSupported = false;
Inside the LightBox constructor, that Boolean is set to true. Where customized built-ins are unsupported, the constructor never runs, so the flag stays false — a direct feature test.
Next, define the autonomous element that will stand in as the polyfill:
customElements.define(
"lightbox-polyfill", // We extend the general HTMLElement instead of a specific one
class LightBoxPoly extends HTMLElement {
constructor() {
super();
// This part is the same as the customized built-in element’s constructor
let lb = document.createElement("div");
lb.style.display = "none";
lb.style.position = "absolute";
lb.style.height = "100vh";
lb.style.width = "100vw";
lb.style.top = 0;
lb.style.left = 0;
lb.style.background =
"rgba(0,0,0, 0.7) url(" + this.dataset.lbsrc + ") no-repeat center";
lb.style.backgroundSize = "contain";
// Here’s where things start to diverge. We add a `shadowRoot` to the autonomous custom element because we can’t add child nodes directly to the custom element in the constructor. We could use an HTML template and slots for this, but since we only need two elements, it's easier to just create them in JavaScript.
const shadowRoot = this.attachShadow({ mode: "open" });
// We create an image element to display the image on the page
let lbpimg = document.createElement("img");
// Grab the `src` and `alt` attributes from the autonomous custom element and set them on the image
lbpimg.setAttribute("src", this.getAttribute("src"));
lbpimg.setAttribute("alt", this.getAttribute("alt"));
// Add the div and the image to the `shadowRoot`
shadowRoot.appendChild(lb);
shadowRoot.appendChild(lbpimg);
// Set the event listeners so that you show the div when the image is clicked, and hide the div when the div is clicked.
lb.addEventListener("click", function (evt) {
this.style.display = "none";
});
lbpimg.addEventListener("click", function (evt) {
lb.style.display = "block";
});
}
}
);
Finally, the replacement logic: when the test fails, the customized <img> is swapped for the polyfill element.
if (!customBuiltInElementsSupported) {
// Select any image with the `is` attribute set to `light-box`
let lbimgs = document.querySelectorAll('img[is="light-box"]');
for (let i = 0; i < lbimgs.length; i++) { // Go through all light-box images
let replacement = document.createElement("lightbox-polyfill"); // Create an autonomous custom element
// Grab the image and div from the `shadowRoot` of the new lighbox-polyfill element and set the attributes to those originally on the customized image, and set the background on the div.
replacement.shadowRoot.querySelector("img").setAttribute("src", lbimgs[i].getAttribute("src"));
replacement.shadowRoot.querySelector("img").setAttribute("alt", lbimgs[i].getAttribute("alt"));
replacement.shadowRoot.querySelector("div").style.background =
"rgba(0,0,0, 0.7) url(" + lbimgs[i].dataset.lbsrc + ") no-repeat center";
// Stick the new lightbox-polyfill element into the DOM just before the image we’re replacing
lbimgs[i].parentNode.insertBefore(replacement, lbimgs[i]);
// Remove the customized built-in image
lbimgs[i].remove();
}
}
The result is custom functionality that works across browsers while retaining semantic, structured HTML that screen readers and search engines can interpret.



