Web Components

Build a new kind of element

HTML gives you ready-made elements, such as <button> and <input>. Web Components let you make your own. They are features built into the browser, so you need no framework and no build step.

With Web Components you can:

• Teach the browser a new tag, such as <cf-wc-counter>, and give it a class that says how it behaves.
• Run your own code when the element is added to the page or taken off it.
• Hide the element's inside parts in a shadow root. That is a private area that page styles can't reach.
• Leave openings, called slots, where content from the page shows through.

This lesson uses ideas from Class basics, Creating & changing elements, Bubbling & capturing, and Custom events. The new idea here is the boundary: the line between the element's private inside and the rest of the page. You will learn what stays inside, what the page controls, and what is allowed to cross.

A custom element is a new HTML tag that you define. You make one in two steps:

1. Write a class that extends HTMLElement. HTMLElement is the class behind every ordinary HTML element, so your class gets everything they can do.
2. Register a tag name for it with customElements.define(name, Class). customElements is the browser's registry: its list of known custom tag names.

The tag name has three rules:

• It starts with a lowercase letter.
• It has no capital letters.
• It contains a hyphen (-), such as profile-card.

The hyphen keeps your names apart from built-in tags. No new built-in HTML tag will ever have a hyphen, so a future tag can never take your name.

Each name can be registered only once per page. If you call customElements.define("cf-wc-counter", Counter) a second time, it throws a NotSupportedError. On this site, a lesson's code can run more than once. That happens when you leave a lesson and come back without a full reload. It also happens in React's Strict Mode, which runs setup code twice while the site is being built. So every demo here does two things:

• It registers elements only in the browser, never on the server.
• It first calls customElements.get(name). That gives back the class if the name is already taken, or undefined if the name is free.

class ProfileCard extends HTMLElement {}
customElements.define("cf-wc-profile-card", ProfileCard);
customElements.define("cf-wc-profile-card", ProfileCard);

Line 2 registers the name. Line 3 tries to register it again. The registry does not swap in the new class. It throws NotSupportedError instead. That is why code that can run twice needs a check first.

const card = document.createElement("cf-wc-upgrade-demo");
console.log(card instanceof HTMLElement);
document.body.append(card);
class UserCard extends HTMLElement {}
customElements.define("cf-wc-upgrade-demo", UserCard);
console.log(card instanceof UserCard);

Line 1 makes an element called cf-wc-upgrade-demo. No class is registered for that name yet, so it is a plain element. Line 2 prints true: it is an HTMLElement. Line 3 puts it on the page. Line 4 writes the class, and line 5 registers it. The browser now finds the tag already on the page and turns it into a UserCard. This is called an upgrade. Line 6 prints true.

An element that is not on the page is not upgraded by itself. If you need it upgraded right away, call customElements.upgrade(element).

Sometimes your code must wait until a tag's class is registered. For example, it may want to call a method that only the class has. customElements.whenDefined("profile-card") gives you a promise: an object that settles later, here when the name is registered. It only waits. It never registers the class for you.

const name = "cf-wc-ready-badge";
const ready = customElements.whenDefined(name);
console.log(ready instanceof Promise);
class ReadyBadge extends HTMLElement {}
customElements.define(name, ReadyBadge);
console.log(customElements.get(name) === ReadyBadge);

Line 2 starts waiting before the class even exists. Line 3 prints true, because ready is a promise. Line 5 registers the class, and that settles the promise. Line 6 prints true: the registry now gives back ReadyBadge for the name. Waiting doesn't make a second define safe, so you still need the check from before.

The browser also calls special methods on your element at key moments in its life. They are called lifecycle callbacks:

• The constructor runs when the element is created.
• connectedCallback runs each time the element is added to the page.
• disconnectedCallback runs each time the element is taken off the page.
• attributeChangedCallback runs when a watched attribute changes. You list the attributes to watch in static observedAttributes. A static field belongs to the class itself, not to each element.

Elements have attributes and properties. An attribute is written in HTML, like count="2", and it always holds text. A property is a value on the JavaScript object, like element.count, and it can be any type. The counter below reflects its property: setting element.count also writes the count attribute.

Try the counter. It is a real custom element that watches count and step. It starts with count="2" and step="3". Use the buttons to:

• set the count attribute to 10;
• set the count property to 21;
• read both back.

You can also click the counter's own button. It adds the step, 3, to the count. The log lists each callback that ran.

1class CounterBadge extends HTMLElement {2  static observedAttributes = ["count", "step"];3 4  set count(value) {5    this.setAttribute("count", String(value));6  }7 8  connectedCallback() {9    this.render();10  }11 12  attributeChangedCallback(name, oldValue, newValue) {13    if (oldValue !== newValue) this.render();14  }15}16 17customElements.define("cf-wc-counter", CounterBadge);

class ClickCounter extends HTMLElement {
  count = 0;
  connectedCallback() {
    this.innerHTML = "<button>0</button>";
    this.querySelector("button").addEventListener("click", () => {
      this.querySelector("button").textContent = String(++this.count);
    });
  }
}

customElements.define("cf-wc-click-counter", ClickCounter);
const counter = document.createElement("cf-wc-click-counter");
document.body.append(counter);
counter.querySelector("button").click();
console.log(counter.querySelector("button").textContent);

Line 2 starts the count at 0. When the element is added to the page, connectedCallback (line 3) puts a button inside it (line 4). Line 5 listens for clicks. Each click adds 1 to the count and shows the new number (line 6). Line 14 clicks the button once, so line 15 prints 1.

const countAttribute = "2";
const countProperty = Number(countAttribute);
console.log(typeof countAttribute, countAttribute);
console.log(typeof countProperty, countProperty);

Line 1 holds the count as text, the way an attribute stores it. Line 2 turns that text into a number with Number(). Lines 3 and 4 print the type and the value of each: string 2, then number 2. If a property and an attribute describe the same thing, keep them in step. Turn the text into a number where your component reads it, and check that the result really is a number.

const button = document.createElement("button");
button.setAttribute("disabled", "false");
console.log(button.disabled);
button.removeAttribute("disabled");
console.log(button.disabled);

Some attributes, like disabled, are on/off switches. For these, only one thing matters: is the attribute there or not? Line 2 sets disabled to the text "false". The attribute is still there, so line 3 prints true. Line 4 removes it, so line 5 prints false.

The order matters. Many components start work when they are added to the page: they load data, add listeners, or measure their size. They clean that work up when they are taken off. So:

• The constructor should only set up the element's own starting values. The element is not on the page yet.
• connectedCallback can run more than once for the same element. It runs again each time the element is moved, or taken off and added back.

The step-through below copies the order a real browser uses. It is a model written in plain JavaScript, so the site's tests can check it. The same order was also checked in Chrome. Pick a setting, then guess: does the attribute callback come before or after the first connectedCallback?

1const el = document.createElement("cf-wc-lifecycle");Run2el.setAttribute("count", "2");3left.append(el);4right.append(el);5el.remove();6left.append(el);

Line 4 moves the element from left to right. A move takes the element off the page and then adds it again. So you see disconnectedCallback first, then connectedCallback.

The DOM is the tree of elements that makes up a page. Shadow DOM gives one element its own small, separate tree. That tree starts at a shadow root. The element that holds the shadow root is called the host. You make one with this.attachShadow({ mode: "open" }).

The boundary works both ways:

• CSS rules on the page don't reach the elements inside the shadow root.
• CSS rules inside the shadow root don't leak out to the page.

The host itself is still a normal element on the page. You can place it, set its attributes, and listen for its events.

Try the lab below. It shows a page paragraph and a component with its own shadow paragraph. The page has a CSS rule that colors its paragraphs red.

• The rule colors the page paragraph, but not the shadow paragraph.
• Switch between open and closed mode. Watch what element.shadowRoot gives back.
• Switch the accent color. It is a CSS custom property, a variable in CSS written like --wc-accent. Custom properties pass through the boundary, so the page can change the shadow text color on purpose.

The lab's code also uses :host, ::slotted(), and part. You will meet each one below.

1class NoticeCard extends HTMLElement {2  constructor() {3    super();4    const root = this.attachShadow({ mode: "open" });5    root.innerHTML = `<style>6      :host { --wc-accent: royalblue; display: block; }7      p { color: var(--wc-accent); }8      ::slotted(strong) { text-decoration: underline; }9      [part="label"] { font-weight: bold; }10    </style>11    <p part="label">Shadow paragraph</p>12    <slot name="title">Fallback title</slot>13    <slot>Fallback body</slot>`;14  }15}

:host {
  display: block;
  --wc-accent: royalblue;
}

cf-wc-counter::part(button) {
  border-color: var(--wc-accent);
}

This CSS shows two tools:

• :host (lines 1 to 4) is written inside the shadow root. It styles the host element itself.
• ::part(button) (lines 6 to 8) is written on the page. It styles an inside element that the component marked with part="button".

Page CSS can't reach that button any other way. Only add a part name if you are happy to keep it working for everyone who uses your component.

A <template> element holds HTML that the browser reads but does not show. Nothing inside it appears or runs. To use it, you copy its contents with template.content.cloneNode(true). Components copy one template into each new element, so every element of that tag gets the same inside parts.

A slot is an opening in the shadow tree. The host's own children, the ones the page wrote between the host's tags, show up through it. Those children are called the light DOM: they belong to the page, not to the shadow root.

• A named slot, like <slot name="title">, shows the children that have a matching slot="title" attribute.
• The default slot, a <slot> with no name, shows all the other children.
• Text written inside a slot is fallback text. It shows only when no child goes to that slot.

<cf-wc-user-card>
  <strong slot="name">Asha</strong>
  <span>Writes tools</span>
</cf-wc-user-card>

The strong element has slot="name", so it shows in the slot named name. The span has no slot name, so it shows in the default slot. This is only the page's side of the HTML, not a whole component, so there is nothing to run.

Slotted children are not moved into the shadow root. They stay children of the host. The slot only decides where they appear. To style them from inside the component, use ::slotted(). It only matches the slotted children themselves, not elements nested inside them.

In the lab, switch the title child and the body child on and off. Watch the fallback text appear when a slot is empty. The slotchange event fires on a slot each time the children shown in it change.

1const template = document.querySelector("#profile-template");2const root = host.attachShadow({ mode: "open" });3root.append(template.content.cloneNode(true));4 5root.querySelector("slot[name='title']")6  .addEventListener("slotchange", logAssignedNodes);7 8host.innerHTML = `<strong slot="title">Ada</strong>9<span>Writes tools</span>`;

Every crossing of the boundary should be on purpose. For styling, a component has three tools:

• CSS custom properties, for theme values like a brand color;
• ::part(), for named inside elements;
• slots, for content the page owns.

For events, two words matter:

• Retargeted: when an event leaves a shadow root, listeners outside see the host as event.target, not the inside element. (event.target is the element where the event started.)
• Composed: an event with composed: true is allowed to cross the boundary. Without it, the event stays inside the shadow root.

Try the lab. Click the button inside the shadow root, and compare the target seen inside with the target seen outside. Then send a custom event with composed set to false, then to true, and see whether the page hears it.

1shadowButton.addEventListener("secret", (event) => {2  console.log("inside target:", event.target.localName);3});4 5document.addEventListener("secret", (event) => {6  console.log("outside target:", event.target.localName);7});8 9shadowButton.dispatchEvent(new CustomEvent("secret", {10  bubbles: true,11  composed: true,12}));

shadowButton.addEventListener("secret", (event) => {
  console.log("inside target:", event.target.localName);
});

document.addEventListener("secret", (event) => {
  console.log("outside target:", event.target.localName);
});

shadowButton.dispatchEvent(new CustomEvent("secret", {
  bubbles: true,
  composed: true,
}));

Here the button lives in the shadow root of a div host. Line 9 sends a custom event called secret from the button. Line 10 lets it bubble, which means move up from the button to its parents. Line 11 lets it cross the boundary. Both listeners run:

• The inside listener (line 1) sees the real button, so it prints inside target: button.
• The outside listener (line 5) sees the host, so it prints outside target: div.

Leave out composed, or set it to false, when the event should stay private.

Now sort some common needs by where they belong. Ask the same question each time: should the page own this, should the component own it, or should it be a planned bridge between them?

Where you will use this

Web Components work best when one piece of a page must work in many places, whatever framework each page uses. For example:

• buttons from a company's design system (its shared set of styled parts), used by several teams;
• help widgets added to plain HTML pages;
• a map picker that plain HTML pages can use;
• a small dashboard card shared by a React page and a page built on the server.

They are not always the best choice:

• If a widget is only used inside one React app, a React component is often simpler.
• If a form must send its own input fields directly, keeping them in the light DOM may be easier than Shadow DOM.
• If page CSS needs to style many inside parts, offer a small set of parts. Don't let users depend on your inside class names.

The table below puts the five pieces side by side. Read each row as: this piece is in charge of this, it does this job, and here is a common mistake.

A custom element does not join a form by itself, even with Shadow DOM. To let it send a value with a form:

1. Set static formAssociated = true on the class.
2. Check that attachInternals() exists. It gives you an ElementInternals object, which lets the element set its form value.
3. If it doesn't exist, keep a normal <input> or another fallback.

class CheckoutField extends HTMLElement {
  static formAssociated = true;
}

console.log(CheckoutField.formAssociated);
console.log(typeof HTMLElement.prototype.attachInternals === "function");

Line 2 turns form support on for the class. Line 5 prints true. Line 6 prints true when the browser has attachInternals().

Common misconceptions

Answer once, then read every explanation. The wrong answers show mistakes that even experienced developers make.

Key takeaways

• A custom element name starts with a lowercase letter and has a hyphen. You can register each name only once per page.
• connectedCallback and disconnectedCallback run when the element is added to the page and taken off. attributeChangedCallback runs only for names in observedAttributes.
• Shadow DOM keeps an element's inside parts and styles private. Open or closed mode changes what scripts can read. It is not security.
• A template holds HTML to copy. Slots show the page's children inside the component. ::part() and custom properties let the page style chosen parts.
• Events that leave a shadow root are retargeted to the host. A custom event needs composed: true to leave at all.

Up next: The iteration protocols.