# Web components

## What it is

Web components, also written Web Components with capitals, is the usual name for a group of browser features that let authors define their own HTML elements. A page then uses such an element like any other tag. The standards speak of the parts by their own names: custom elements and the `template` and `slot` elements in the HTML Standard, and shadow trees in the DOM Standard. The collective name is the title of a W3C Working Group Note of 24 July 2014, _Introduction to Web Components_, which the W3C has since discontinued and marked as a document that should not be referenced.

A custom element is defined by a JavaScript class that extends `HTMLElement` and is registered under a name with `customElements.define()`. The definition tells the HTML parser how to construct the element and how it should react to changes, and from then on the element can be created from markup, with `document.createElement()` or with `new`. Its name starts with a lower-case ASCII letter, contains no upper-case ASCII letters and must contain a hyphen. The hyphen keeps custom names apart from the language itself: the HTML Standard says that HTML, SVG and MathML will not gain any element whose name contains a hyphen.

There are two kinds. An autonomous custom element, such as the standard's own `<flag-icon country="nl">`, starts from a plain element with no built-in meaning. A customized built-in element extends an existing one: a class that extends `HTMLButtonElement`, registered with `{ extends: "button" }` and used as `<button is="plastic-button">`, keeps everything that makes a button a button, including focus behaviour, form submission and the `disabled` attribute.

A shadow tree is a separate tree of nodes attached to an element, which is called its host; the DOM Standard calls the host's ordinary tree the light tree. `attachShadow()` creates a shadow root in open or closed mode, and only in open mode does the host's `shadowRoot` property return it. A `slot` element in the shadow tree marks where the host's own children appear. It shows the nodes assigned to it, or its own contents when there are none, and a named slot takes the children whose `slot` attribute carries its name. The `template` element holds a fragment of HTML that is not rendered and that a script can clone. With a `shadowrootmode` attribute, a `template` represents a declarative shadow root, so a shadow tree can also be written straight into the markup.

## Why it matters

A made-up tag used to be of little use: the HTML Standard looks back on such elements as invalid and of little practical use. A custom element is a full member of the document. The parser constructs it, the DOM methods create it, and its class decides what happens when its attributes change or when it enters or leaves a page.

The definition does not have to arrive first. An element the parser has already created becomes a custom element once a definition for its name is registered, and the HTML Standard calls this upgrading. Until then the element is treated as an undefined element, much like a `span`, so the text and links inside it are shown as they are. The standard says in so many words that upgrades allow the content of a custom element to be progressively enhanced.

A custom element can also take part in forms and in the accessibility tree. A class that sets `static formAssociated = true` and calls `attachInternals()` gets an `ElementInternals` object, and `setFormValue()` on that object gives the element a value that its form submits like any other control's. The same object sets a default ARIA role and default ARIA states, which apply unless the page author overrides them with the `role` attribute or the matching `aria-*` attributes, and it can hold custom states that style sheets match with the `:state()` pseudo-class.

For a team, the shadow tree is what makes a component self-contained: ordinary page selectors do not cross into its internal shadow tree, and the component decides which parts to expose for outside styling. Inherited values and custom properties can still enter, and slotted light-tree content remains subject to page selectors. Where several libraries share a page, the HTML Standard offers scoped registries, created with `new CustomElementRegistry()`, so that their elements can coexist without the libraries having to coordinate their names.

## What it looks like in practice

A product card shows the parts working together. The page holds the content as ordinary markup, with a `slot` attribute on the element that should go into a named slot:

```html
<product-card>
  <span slot="name">Oak stool</span>
  <a href="/shop/oak-stool/">See the details</a>
</product-card>
<script type="module" src="product-card.mjs"></script>
```

The module defines the element. The template is built once, and every card gets its own copy of it in an open shadow root:

```js
const template = document.createElement("template");
template.innerHTML = `
  <h2 part="title"><slot name="name">Unnamed product</slot></h2>
  <slot></slot>
`;

class ProductCard extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: "open" });
    root.append(template.content.cloneNode(true));
  }
}

if (!customElements.get("product-card")) {
  customElements.define("product-card", ProductCard);
}
```

The page styles the title through the one part the component exposes:

```css
product-card::part(title) {
  font-size: 1.25rem;
}
```

Before `product-card.mjs` has run, the card is an undefined element and the reader sees the product name and the link as plain inline content. When the module runs, `define()` registers the class and the card already in the page is upgraded. Its constructor attaches a shadow root and fills it with a clone of the template's contents. The `span` is assigned to the slot called `name` and appears inside the heading. The link has no `slot` attribute, so it goes to the unnamed default slot. A card without a name shows the slot's own contents, “Unnamed product”, in its place. The `customElements.get()` check keeps a second copy of the module, arriving in another bundle, from making `define()` throw.

Shared components help only if people use them, and this site's portfolio has a case about that. The iOS 26 “Liquid Glass” design system starts from a UI in which every new screen reinvents its own buttons, badges and cards, each a little different, until every change means touching five bespoke versions. The answer described there is a canonical set of components that every screen composes from, among them Card, Label, Button, GlassIconButton and DirectoryGrid, with lint rules that reject a hand-rolled badge or chip and point to the canonical component. The page does not say whether those components are custom elements, but the discipline carries over: one definition per component, kept in force by tooling rather than by a reviewer's memory. The custom element registry enforces the first half by refusing a second definition for a name.

## Where it goes wrong

A hyphenated name stands in for a role. “An autonomous custom element does not have any special meaning: it represents its children,” says the HTML Standard. Its `taco-button` example shows the cost: to act as a button, the element needs a `tabindex`, the ARIA role `button`, an accessible name, `aria-disabled`, key handlers that turn Enter and Space into clicks, and styles for the disabled state. Even then, a custom element cannot declare default focus behaviour, so `tabindex="0"` may not match how buttons behave on the platform. Where the element builds on an existing one, the standard says extending a built-in element reduces the work for both its author and the people using it. For an autonomous element, set its default role and states through `ElementInternals` rather than leaving them to every page that uses it.

The constructor does the work. The HTML Standard sets rules for custom element constructors: `super()` with no arguments comes first, the constructor must not look at the element's attributes or children, because an element created rather than upgraded has none, and the element must not gain attributes or children of its own. A constructor that breaks these rules can produce an element that the parser or the DOM methods cannot create. Use the constructor for initial state, default values, event listeners and the shadow root, and move fetching and rendering to `connectedCallback`.

`connectedCallback` is expected to run once. It can run more than once. By default, moving an element runs `disconnectedCallback` and then `connectedCallback`, so the element resets its state as if it had been removed and inserted again. Guard set-up that must happen only once with a flag, and undo in `disconnectedCallback` what `connectedCallback` started. If an element should keep its state when it is moved with `moveBefore()`, define `connectedMoveCallback`, whose presence alone replaces the default pair, even with an empty body.

A name is defined twice. `customElements.define()` throws a `NotSupportedError` when the name or the class is already registered, and a `SyntaxError` when the name is not valid, for example because it has no hyphen or contains a capital letter. Check with `customElements.get()` before defining, and give a library that must coexist with others a scoped registry of its own.

Closed mode is treated as protection. Closed mode hides the root from the host's `shadowRoot` property and hides internal nodes from an event's composed path as seen by listeners outside that closed shadow tree. CSS Shadow Parts states plainly that shadow trees are deliberately not a security boundary, only a convenience for page authors. Keep secrets out of components, and choose closed mode for its effect on outside code, not as a lock.

`attachShadow()` is called where it cannot work. The DOM Standard allows a shadow root only on elements with a valid custom element name and on a short list of built-in ones, among them `div`, `section`, `p` and `span`, but not `button`. On a customized built-in button, the call throws a `NotSupportedError`. It also behaves differently on an element that already has a root: if that root is declarative and of the same mode, the call removes everything in it and returns it empty, and otherwise it throws. Check for an existing shadow root first, so that markup sent from the server in a declarative root is kept rather than wiped.

Page styles are expected to reach inside. CSS Shadow Parts calls the boundary a styling barrier, and notes that it also makes a component harder to style when the page wants to. Expose the elements a page may style with `part`, and style them from outside with `::part()`. A component nested inside another needs `exportparts` on the inner host to pass its parts on to the page. For colours and spacing that should follow the page, read custom properties set on the host, which reach the shadow tree by inheritance.

The content exists only after the script. A component that writes all its text from JavaScript shows readers none of it until the definition has loaded, and none at all if the script fails. Keep the content in the light tree and assign it to slots, as the product card does, so that upgrading enhances what is already there. Where content must wait, the HTML Standard's own example hides it until `customElements.whenDefined()` has resolved for every element matching `:not(:defined)`.

## Further reading
* HTML Standard: Custom elements — naming rules, constructor requirements, upgrades, form-associated elements and `ElementInternals`, with worked examples.
* DOM Standard: Shadow tree — shadow roots and their hosts, slots and the nodes assigned to them, and the steps behind `attachShadow()`.
* HTML Standard: Scripting — the `template` element with its `shadowrootmode` attribute, and the `slot` element.
* CSS Shadow Parts — the W3C Working Draft of 16 December 2025 that defines `part`, `exportparts` and the `::part()` pseudo-element.

=> https://www.w3.org/TR/components-intro/ _Introduction to Web Components_
=> /portfolio/designed-an-ios-26-liquid-glass-design-system/ The iOS 26 “Liquid Glass” design system
=> https://html.spec.whatwg.org/multipage/custom-elements.html HTML Standard: Custom elements
=> https://dom.spec.whatwg.org/#shadow-trees DOM Standard: Shadow tree
=> https://html.spec.whatwg.org/multipage/scripting.html HTML Standard: Scripting
=> https://www.w3.org/TR/css-shadow-parts-1/ CSS Shadow Parts

=> https://engineer.company/glossary/web-components/ This page on the web
