# Web Components

## Was es ist

Web Components ist die übliche Sammelbezeichnung für Browserfunktionen, mit
denen Autoren eigene HTML-Elemente definieren können. Eine Seite verwendet ein
solches Element anschließend wie jedes andere Tag. Im Englischen wird der
Begriff auch kleingeschrieben. Die Standards benennen die Teile einzeln:
Custom Elements sowie die Elemente `template` und `slot` im HTML-Standard,
Shadow Trees im DOM-Standard. Der Sammelbegriff steht im Titel einer W3C
Working Group Note vom 24. Juli 2014,
[_Introduction to Web Components_](https://www.w3.org/TR/components-intro/).
Das W3C hat dieses Dokument inzwischen eingestellt und als nicht mehr zu
referenzieren gekennzeichnet.

Ein Custom Element wird durch eine JavaScript-Klasse definiert, die
`HTMLElement` erweitert und mit `customElements.define()` unter einem Namen
registriert wird. Die Definition legt fest, wie der HTML-Parser das Element
erzeugt und wie es auf Änderungen reagiert. Danach lässt es sich aus Markup,
mit `document.createElement()` oder mit `new` erstellen. Sein Name beginnt mit
einem kleinen ASCII-Buchstaben, enthält keine großen ASCII-Buchstaben und muss
einen Bindestrich enthalten. Dieser trennt eigene Namen von der Sprache selbst:
Laut HTML-Standard werden HTML, SVG und MathML keine neuen Elemente mit
Bindestrich im Namen erhalten.

Es gibt zwei Arten. Ein autonomes Custom Element wie das standardeigene
`<flag-icon country="nl">` beginnt als einfaches Element ohne eingebaute
Bedeutung. Ein angepasstes eingebautes Element erweitert dagegen ein
vorhandenes. Eine Klasse, die `HTMLButtonElement` erweitert, mit
`{ extends: "button" }` registriert und als `<button is="plastic-button">`
verwendet wird, behält alles, was einen Button ausmacht: Fokusverhalten,
Formularübermittlung und das Attribut `disabled`.

Ein Shadow Tree ist ein gesonderter Knotenbaum, der an einem Element hängt.
Dieses Element heißt Host; seinen gewöhnlichen Baum nennt der DOM-Standard
Light Tree. `attachShadow()` erzeugt eine Shadow Root im offenen oder
geschlossenen Modus. Nur im offenen Modus gibt die Eigenschaft `shadowRoot`
des Hosts diese Wurzel zurück. Ein `slot`-Element im Shadow Tree markiert, wo
die eigenen Kinder des Hosts erscheinen. Es zeigt die zugewiesenen Knoten
oder, wenn keine vorhanden sind, seinen eigenen Inhalt. Ein benannter Slot
nimmt Kinder auf, deren Attribut `slot` seinen Namen trägt. Das Element
`template` enthält ein nicht gerendertes HTML-Fragment, das ein Skript klonen
kann. Mit dem Attribut `shadowrootmode` stellt ein `template` eine deklarative
Shadow Root dar. Ein Shadow Tree lässt sich deshalb auch direkt ins Markup
schreiben.

## Warum es wichtig ist

Ein erfundenes Tag war früher wenig nützlich. Rückblickend bezeichnet der
HTML-Standard solche Elemente als ungültig und von geringem praktischem
Nutzen. Ein Custom Element ist dagegen ein vollwertiger Teil des Dokuments.
Der Parser erzeugt es, DOM-Methoden erstellen es, und seine Klasse entscheidet,
was bei Attributänderungen oder beim Einfügen in eine Seite und beim Entfernen
daraus geschieht.

Die Definition muss nicht zuerst eintreffen. Ein vom Parser bereits erzeugtes
Element wird zum Custom Element, sobald eine Definition für seinen Namen
registriert ist. Der HTML-Standard nennt das Upgrading. Bis dahin gilt es als
undefiniertes Element, ähnlich einem `span`: Text und Links darin erscheinen
unverändert. Der Standard sagt ausdrücklich, dass Upgrades es erlauben, den
Inhalt eines Custom Elements schrittweise zu erweitern.

Ein Custom Element kann auch an Formularen und am Barrierefreiheitsbaum
teilnehmen. Eine Klasse, die `static formAssociated = true` setzt und
`attachInternals()` aufruft, erhält ein `ElementInternals`-Objekt. Dessen
`setFormValue()` gibt dem Element einen Wert, den sein Formular wie den jedes
anderen Bedienelements übermittelt. Dasselbe Objekt legt eine voreingestellte
ARIA-Rolle und ARIA-Zustände fest. Diese gelten, sofern der Seitenautor sie
nicht durch das Attribut `role` oder die passenden `aria-*`-Attribute
überschreibt. Es kann außerdem benutzerdefinierte Zustände enthalten, die
Stylesheets mit der Pseudoklasse `:state()` auswählen.

Für ein Team sorgt der Shadow Tree dafür, dass eine Komponente in sich
gekapselt ist: Gewöhnliche Seitenselektoren reichen nicht in ihren internen
Shadow Tree hinein, und die Komponente legt fest, welche Teile von außen
gestaltet werden dürfen. Geerbte Werte und Custom Properties können weiterhin
hineingelangen. Über Slots angezeigter Inhalt aus dem Light Tree bleibt den
Seitenselektoren zugänglich. Teilen sich mehrere Bibliotheken eine Seite,
bietet der HTML-Standard lokal begrenzte Registries, erzeugt mit
`new CustomElementRegistry()`. So können ihre Elemente nebeneinander bestehen,
ohne dass die Bibliotheken ihre Namen abstimmen müssen.

## Wie es in der Praxis aussieht

Eine Produktkarte zeigt das Zusammenspiel. Die Seite hält den Inhalt als
gewöhnliches Markup vor. Das Element, das in einen benannten Slot gehört,
erhält das Attribut `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>
```

Das Modul definiert das Element. Die Vorlage wird einmal aufgebaut, und jede
Karte erhält eine eigene Kopie davon in einer offenen 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);
}
```

Die Seite gestaltet die Überschrift über den einen Teil, den die Komponente
nach außen freigibt:

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

Bevor `product-card.mjs` ausgeführt wurde, ist die Karte ein undefiniertes
Element. Leser sehen den Produktnamen und den Link als gewöhnlichen
Inline-Inhalt. Beim Ausführen registriert `define()` die Klasse, und die
bereits vorhandene Karte erhält ihr Upgrade. Ihr Konstruktor hängt eine
Shadow Root an und füllt sie mit einem Klon des Vorlageninhalts. Das `span`
wird dem Slot namens `name` zugewiesen und erscheint innerhalb der
Überschrift. Der Link hat kein Attribut `slot` und landet deshalb im
unbenannten Standardslot. Bei einer Karte ohne Namen erscheint stattdessen
der eigene Inhalt des Slots, „Unnamed product“. Die Prüfung mit
`customElements.get()` verhindert, dass eine zweite, über ein anderes Bundle
eintreffende Modulkopie bei `define()` eine Ausnahme auslöst.

Gemeinsame Komponenten helfen nur, wenn sie verwendet werden. Das Portfolio
dieser Website enthält einen Fall dazu.
[Das Designsystem für iOS 26 „Liquid Glass“](/de/portfolio/designed-an-ios-26-liquid-glass-design-system/)
geht von einer Oberfläche aus, in der jeder neue Bildschirm Buttons, Badges
und Karten neu erfindet, jeweils etwas anders. Jede Änderung betrifft dadurch
fünf eigens gebaute Varianten. Die dort beschriebene Antwort ist ein
verbindlicher Komponentensatz, aus dem jeder Bildschirm zusammengesetzt wird.
Dazu gehören Card, Label, Button, GlassIconButton und DirectoryGrid.
Lint-Regeln lehnen selbst gebaute Badges oder Chips ab und verweisen auf die
verbindliche Komponente. Die Seite sagt nicht, ob diese Komponenten Custom
Elements sind. Die Arbeitsweise lässt sich aber übertragen: eine Definition
je Komponente, durch Werkzeuge durchgesetzt statt durch das Gedächtnis eines
Reviewers. Die Custom-Element-Registry erzwingt die erste Hälfte, indem sie
eine zweite Definition für denselben Namen ablehnt.

## Wo es schiefgeht

**Ein Name mit Bindestrich ersetzt eine Rolle.** „Ein autonomes Custom Element
hat keine besondere Bedeutung: Es repräsentiert seine Kinder“, sagt der
HTML-Standard. Sein Beispiel `taco-button` zeigt den Aufwand. Um als Button
zu funktionieren, benötigt das Element `tabindex`, die ARIA-Rolle `button`,
einen zugänglichen Namen, `aria-disabled`, Tastaturhandler, die Enter und
Leertaste in Klicks umsetzen, und Stile für den deaktivierten Zustand. Selbst
dann kann ein Custom Element kein voreingestelltes Fokusverhalten deklarieren.
`tabindex="0"` entspricht deshalb möglicherweise nicht dem Buttonverhalten der
Plattform. Baut das Element auf einem vorhandenen auf, verringert die
Erweiterung eines eingebauten Elements laut Standard die Arbeit sowohl für
seinen Autor als auch für seine Nutzer. Bei einem autonomen Element sollten
die voreingestellte Rolle und die Zustände über `ElementInternals` festgelegt
werden, statt dies jeder verwendenden Seite zu überlassen.

**Der Konstruktor erledigt die eigentliche Arbeit.** Der HTML-Standard stellt
Regeln für Custom-Element-Konstruktoren auf. Zuerst kommt `super()` ohne
Argumente. Der Konstruktor darf Attribute und Kinder des Elements nicht lesen,
weil ein neu erzeugtes statt nachträglich aufgewertetes Element noch keine
hat. Er darf dem Element auch keine eigenen Attribute oder Kinder hinzufügen.
Ein Verstoß kann ein Element ergeben, das weder der Parser noch DOM-Methoden
erzeugen können. In den Konstruktor gehören Anfangszustand, Voreinstellungen,
Event Listener und die Shadow Root; Abruf und Rendering gehören in
`connectedCallback`.

**`connectedCallback` soll nur einmal laufen.** Er kann mehrfach laufen.
Standardmäßig löst das Verschieben eines Elements erst `disconnectedCallback`
und dann `connectedCallback` aus. Das Element setzt seinen Zustand zurück, als
wäre es entfernt und wieder eingefügt worden. Einmalige Einrichtung braucht ein
Flag als Schutz. In `disconnectedCallback` sollte aufgeräumt werden, was
`connectedCallback` gestartet hat. Soll ein Element beim Verschieben mit
`moveBefore()` seinen Zustand behalten, wird `connectedMoveCallback` definiert.
Schon dessen Vorhandensein ersetzt das übliche Paar, selbst bei leerem
Funktionsrumpf.

**Ein Name wird zweimal definiert.** `customElements.define()` löst einen
`NotSupportedError` aus, wenn der Name oder die Klasse bereits registriert
ist, und einen `SyntaxError`, wenn der Name ungültig ist, etwa weil ihm ein
Bindestrich fehlt oder er einen Großbuchstaben enthält. Vor der Definition
sollte `customElements.get()` prüfen, ob sie bereits vorhanden ist. Eine
Bibliothek, die neben anderen bestehen muss, sollte eine eigene lokal
begrenzte Registry erhalten.

**Der geschlossene Modus gilt als Schutz.** Er verbirgt die Wurzel vor der
Eigenschaft `shadowRoot` des Hosts. Für Event Listener außerhalb dieses
geschlossenen Shadow Trees verbirgt er außerdem interne Knoten aus dem
zusammengesetzten Ereignispfad. CSS Shadow Parts sagt ausdrücklich, dass
Shadow Trees bewusst keine Sicherheitsgrenze bilden, sondern eine Hilfe für
Seitenautoren sind. Geheimnisse gehören nicht in Komponenten. Der geschlossene
Modus wird wegen seiner Wirkung auf äußeren Code gewählt, nicht als Schloss.

**`attachShadow()` wird aufgerufen, wo es nicht funktionieren kann.** Der
DOM-Standard erlaubt eine Shadow Root nur auf Elementen mit einem gültigen
Custom-Element-Namen und auf einer kurzen Liste eingebauter Elemente. Dazu
gehören `div`, `section`, `p` und `span`, aber nicht `button`. Auf einem
angepassten eingebauten Button löst der Aufruf einen `NotSupportedError` aus.
Bei einem Element mit bereits vorhandener Wurzel verhält er sich zudem anders:
Ist diese deklarativ und hat denselben Modus, leert der Aufruf sie und gibt sie
leer zurück. Andernfalls löst er eine Ausnahme aus. Vorher sollte deshalb nach
einer vorhandenen Shadow Root gesucht werden, damit eine vom Server im Markup
gelieferte deklarative Wurzel erhalten bleibt, statt gelöscht zu werden.

**Seitenstile sollen bis ins Innere reichen.** CSS Shadow Parts nennt die
Grenze eine Styling-Barriere und hält fest, dass sie eine Komponente zugleich
schwerer gestaltbar macht, wenn die Seite das möchte. Elemente, die eine Seite
gestalten darf, werden mit `part` freigegeben und von außen mit `::part()`
angesprochen. Eine in einer anderen verschachtelte Komponente benötigt
`exportparts` auf dem inneren Host, um ihre Teile bis zur Seite weiterzureichen.
Farben und Abstände, die der Seite folgen sollen, werden aus Custom Properties
auf dem Host gelesen. Sie erreichen den Shadow Tree durch Vererbung.

**Der Inhalt existiert erst nach dem Skript.** Eine Komponente, die ihren
gesamten Text mit JavaScript schreibt, zeigt Lesern bis zum Laden der
Definition nichts davon. Scheitert das Skript, erscheint überhaupt nichts.
Der Inhalt sollte wie bei der Produktkarte im Light Tree stehen und Slots
zugewiesen werden. Das Upgrade erweitert dann, was bereits vorhanden ist.
Muss Inhalt warten, verbirgt ihn das Beispiel des HTML-Standards, bis
`customElements.whenDefined()` für jedes Element aufgelöst wurde, das
`:not(:defined)` entspricht.

## Weiterführende Lektüre

- [HTML Standard: Custom elements](https://html.spec.whatwg.org/multipage/custom-elements.html)
  — Namensregeln, Anforderungen an Konstruktoren, Upgrades, formulargebundene
  Elemente und `ElementInternals`, mit durchgearbeiteten Beispielen.
- [DOM Standard: Shadow tree](https://dom.spec.whatwg.org/#shadow-trees) —
  Shadow Roots und ihre Hosts, Slots, die ihnen zugewiesenen Knoten und die
  Schritte hinter `attachShadow()`.
- [HTML Standard: Scripting](https://html.spec.whatwg.org/multipage/scripting.html)
  — das Element `template` mit seinem Attribut `shadowrootmode` und das
  Element `slot`.
- [CSS Shadow Parts](https://www.w3.org/TR/css-shadow-parts-1/) — der
  W3C-Arbeitsentwurf vom 16. Dezember 2025, der `part`, `exportparts` und das
  Pseudoelement `::part()` definiert.

<https://engineer.company/de/glossary/web-components/>
