Web Components mit Angular Elements

Ein Custom Element (Web Component) ist ein HTML-Tag, den du selbst definierst — <atlas-rating> — und den der Browser überall erkennt: in einer statischen Seite, in einem CMS, in einer React-Anwendung oder in einer anderen Angular-Anwendung. @angular/elements ist die Brücke: createCustomElement() macht aus einer Angular-Komponente eine Klasse, die HTMLElement erweitert. Inputs werden zu Attributen und Properties, Outputs werden zu CustomEvents, und die Komponente erzeugt sich selbst, sobald der Tag ins DOM kommt.

Die Beispiele auf dieser Seite sind echt: Wir definieren die Elemente zur Laufzeit mit customElements.define, erzeugen sie mit document.createElement in einem Container, den Angular nicht verwaltet, und hören sie mit addEventListener ab — genau so, wie es eine Seite täte, die nichts von Angular weiß. Alles läuft in dieser Anwendung, die zoneless ist.

Was createCustomElement macht

createCustomElement(Component, { injector }) zeigt nichts an. Es liefert eine Klasse (NgElementConstructor) zurück, die du mit customElements.define(tag, klasse) registrierst. Die Klasse liest die Metadaten der Komponente (reflectComponentType) und bereitet drei Dinge vor:

• observedAttributes — die Namen der Inputs in kebab-case (maxStars → max-stars), damit der Browser sie über jede Attributänderung benachrichtigt;
• einen Getter und einen Setter auf dem Prototype für jeden Input, sodass el.maxStars = 7 wie eine gewöhnliche DOM-Property funktioniert;
• eine Strategie (NgElementStrategy), die bei connectedCallback createComponent mit dem Element als hostElement aufruft, die View an ApplicationRef hängt und ein erstes detectChanges() ausführt — synchron, bevor append() zurückkehrt.

Der Injector, den du übergibst, ist die Quelle für die Services der Komponente (HttpClient, Stores, Konfigurations-Tokens). In einem Bundle nur für Widgets bekommst du ihn von createApplication(), einer Anwendung ohne Root-Komponente; in einer bestehenden Anwendung aus ApplicationRef.injector.

import {
  Component,
  ViewEncapsulation,
  booleanAttribute,
  computed,
  input,
  linkedSignal,
  numberAttribute,
  output,
} from '@angular/core';

export interface RatingChange {
  value: number;
  previous: number;
}

@Component({
  selector: 'atlas-rating-cmp',               // ≠ Tag-Name (siehe unten)
  encapsulation: ViewEncapsulation.ShadowDom, // das CSS der Host-Seite kommt nicht hinein
  template: `
    @for (s of stars(); track s) {
      <button type="button" [class.on]="s <= current()" [disabled]="readonly()"
              (click)="pick(s)">★</button>
    }
  `,
})
export class AtlasRating {
  // Attribute: value, max-stars, readonly
  readonly value = input(0, { transform: numberAttribute });
  readonly maxStars = input(5, { transform: numberAttribute });
  readonly readonly = input(false, { transform: booleanAttribute });

  // wird zu einem CustomEvent 'ratingChange', der Wert steckt in event.detail
  readonly ratingChange = output<RatingChange>();

  // lokaler Zustand, wird zurückgesetzt, wenn der Host einen anderen Wert sendet
  protected readonly current = linkedSignal(() => this.value());
  protected readonly stars = computed(() =>
    Array.from({ length: this.maxStars() }, (_, i) => i + 1),
  );

  protected pick(value: number): void {
    const previous = this.current();
    this.current.set(value);
    this.ratingChange.emit({ value, previous });
  }
}

Zone.js wird nicht gebraucht. Ab v19 nutzen die Elemente den gewöhnlichen Change-Detection-Scheduler (Changelog 19.0.0: „switch to ComponentRef.setInput & remove custom scheduler“), und ab v21 sind Anwendungen standardmäßig zoneless. Ein setAttribute landet bei componentRef.setInput(), das die View markiert und ein Rendering einplant; ein Klick im Template des Elements ändert ein Signal — genau wie in einer gewöhnlichen OnPush-Komponente.

Definieren in einer bestehenden Anwendung

Der typische Fall: Die Anwendung erhält HTML aus einem CMS und fügt es mit innerHTML ein. Die Angular-Komponenten in diesem HTML würden nie starten, aber Custom Elements starten von selbst, weil der Browser ihren Tag erkennt.

// In einer bestehenden Anwendung (z. B. HTML aus einem CMS, per innerHTML eingefügt)
import { ApplicationRef, inject, provideAppInitializer } from '@angular/core';
import { createCustomElement } from '@angular/elements';
import { AtlasRating } from './rating';

function defineAtlasElements(): void {
  const injector = inject(ApplicationRef).injector; // Root: lebt so lange wie die Anwendung
  // define() auf einem bereits registrierten Namen wirft NotSupportedError
  if (!customElements.get('atlas-rating')) {
    customElements.define('atlas-rating', createCustomElement(AtlasRating, { injector }));
  }
}

export const appConfig = {
  providers: [provideAppInitializer(defineAtlasElements)],
};

Attribute, Properties, Events

Ein Element hat zwei „Eingänge“ für denselben Input. Das Attribut (max-stars="7") ist immer ein String — deshalb brauchen numerische oder boolesche Inputs transform: numberAttribute / booleanAttribute; ohne Transform wird aus maxStars() + 1 der Wert '71'. Die Property (el.maxStars = 7) akzeptiert jeden Typ, Objekte und Arrays gehen also nur hierüber. Beim Lesen liefert el.maxStars den aktuellen Wert des Inputs; ab v21 gilt das auch für input() auf Signals (früher musste man el.maxStars() aufrufen).

export class Widget {
  // das Attribut = der Name des Inputs (oder sein Alias) in kebab-case
  readonly maxStars = input(5, { transform: numberAttribute });     // max-stars="7"
  readonly compact = input(false, { transform: booleanAttribute }); // compact
  readonly userId = input('', { alias: 'user' });                   // user="42" (!)
  readonly items = input<Item[]>([]);                               // nur als Property

  // ein Output wird zu einem CustomEvent mit dem Namen des Outputs (oder des Alias)
  readonly ratingChange = output<RatingChange>();           // 'ratingChange'
  readonly closed = output<void>({ alias: 'atlasClosed' }); // 'atlasClosed'
}

// Was createCustomElement für die Klasse oben erzeugt:
//   static observedAttributes = ['max-stars', 'compact', 'user', 'items']
//   Getter/Setter auf dem Prototype:  maxStars, compact, userId, items
//   (die Property nutzt den Namen aus der Klasse, das Attribut den Alias)

Das Event wird mit new CustomEvent(name, { detail }) erzeugt — ohne bubbles und ohne composed. Ein Listener auf document oder auf dem übergeordneten Container bekommt nichts mit; du hörst direkt am Element zu. Im Beispiel unten hat der Container ebenfalls einen Listener für ratingChange: Er wird nie im Log auftauchen.

Beachte ein Detail: Nachdem du auf einen Stern geklickt hast, bleibt el.value der Wert, den das Element vom Host erhalten hat. Der Input ist ein Einwegkanal; die Komponente hält die Auswahl in einem linkedSignal und meldet sie per Event. Soll der Host die Quelle der Wahrheit sein, hört er das Event ab und schreibt el.value zurück — das Pattern der „Controlled Component“.

// The event is created as new CustomEvent(name, { detail })
// → bubbles: false, composed: false.
el.addEventListener('ratingChange', (e: Event) => {
  const { value } = (e as CustomEvent<RatingChange>).detail;
});

document.addEventListener('ratingChange', handler); // ✗ empfängt nichts

// Wenn der Host wirklich Delegation braucht (ein Listener für 50 Widgets),
// sende explizit aus der Komponente ein Event, das bubbelt und die Shadow Root durchquert:
export class AtlasRating {
  private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);

  private announce(detail: RatingChange): void {
    this.host.nativeElement.dispatchEvent(
      new CustomEvent('atlas:rating-change', { detail, bubbles: true, composed: true }),
    );
  }
}

Lifecycle

Die Komponente entsteht bei connectedCallback und stirbt bei disconnectedCallback, aber nicht sofort: Die Strategie plant destroy() nach 10 ms ein (DESTROY_DELAY = 10 im Quellcode des Pakets). Kehrt das Element vorher ins DOM zurück — ein Verschieben per remove() + append() im selben Task, etwa beim Sortieren einer Liste —, wird das Zerstören abgebrochen, und der interne Zustand bleibt erhalten. Inputs, die vor dem Verbinden gesetzt werden, werden gemerkt und beim Erzeugen angewendet. Außerdem werden Properties, die auf einem noch nicht definierten Element gesetzt wurden (das Skript des Widgets ist noch nicht geladen), beim Upgrade übernommen, sodass der Host el.items jederzeit setzen kann.

document.createElement('atlas-rating')
    constructor; noch keine Komponente (jetzt gesetzte Inputs werden gemerkt)
container.append(el)
    connectedCallback → createComponent(...) SYNCHRON, attachView(appRef), detectChanges()
el.setAttribute('value', '4')
    attributeChangedCallback → componentRef.setInput('value', '4') → transform → CD
el.value = 4
    setter on the prototype → derselbe Weg, ohne Umwandlung in einen String
el.remove()
    disconnectedCallback → destroy GEPLANT in 10 ms
    ↳ in < 10 ms wieder eingefügt (Move)  destroy abgebrochen: gleiche Instanz, gleicher Zustand
    ↳ nach 10 ms                         componentRef.destroy() → DestroyRef.onDestroy
container.append(el)   // gleiche Instanz, nach destroy
    ⚠︎ die Komponente wird NICHT neu erzeugt: totes HTML + NG0953 in der Konsole
document.createElement('atlas-rating')
    ✓ neue, saubere Instanz

Shadow DOM und Styles

Mit Emulated (Standard) schreibt Angular die Selektoren der Komponente mit eindeutigen Attributen um: Deine Styles lecken nicht nach außen, aber das CSS der Seite kommt hinein. Ein Widget auf einer fremden Website erbt jede Regel wie .content p oder button { text-transform: uppercase !important } — der häufigste Bug bei Widgets. Mit ViewEncapsulation.ShadowDom wird das Template in eine Shadow Root gerendert (Modus open), und die Selektoren der Seite sehen nicht mehr hinein. Nur vererbte Properties (font, color) und CSS-Variablen kommen durch — genau das, was du für ein kontrolliertes Theme brauchst.

Eine wenig bekannte Nuance: Im Modus ShadowDom kopiert Angular in jede Shadow Root auch die Styles der anderen Komponenten derselben Anwendung. Bei Emulated-Komponenten ist das toter Ballast (ihre Selektoren passen nicht), aber eine Komponente mit ViewEncapsulation.None stylt am Ende auch das Innere des Widgets. ExperimentalIsolatedShadowDom (experimentell seit v21) legt nur die eigenen Styles der Komponente in die Shadow Root. Beim SSR werden beide Shadow-Modi als Emulated gerendert.

Shadow DOM ändert mehr als nur Styles: Events, die eine Shadow Root verlassen, werden retargeted (event.target wird zum Host), document.querySelector findet von innen nichts, und E2E-Tests müssen die Shadow Root durchdringen. Für das Theming stellst du CSS-Variablen bereit und, wo mehr Kontrolle nötig ist, part-Attribute, die sich mit ::part() stylen lassen.

@Component({
  selector: 'atlas-card-cmp',
  encapsulation: ViewEncapsulation.ShadowDom,
  template: `
    <h3 part="title">{{ title() }}</h3>
    <ng-content />
  `,
  styles: `
    :host { display: block; }
    /* CSS-Variablen und vererbte Properties (font, color) GELANGEN in die Shadow Root */
    h3 { color: var(--atlas-accent, #2b45d4); font: inherit; font-weight: 650; }
  `,
})
export class AtlasCard {
  readonly title = input('');
}

Build, Bundle, Distribution

Um die Elemente außerhalb einer Angular-Anwendung zu nutzen, brauchst du einen separaten Build: eine Anwendung, deren main.ts createApplication() und customElements.define() aufruft, ohne Root-Komponente. Das Native-Federation-Schematic hat sogar die Option --webcomponent, die genau diesen Bootstrap erzeugt (siehe Micro Frontends).

Der Preis ist die Runtime. Ein einzelnes einfaches Element, mit Angular 22.2.2 im Production-Build, zoneless, kommt auf ≈ 110 kB minifiziert, ≈ 33 kB übertragen (die Schätzung der CLI) — praktisch @angular/core + platform-browser + ein bisschen RxJS. Drei Widgets aus drei verschiedenen Builds auf derselben Seite bedeuten drei Kopien der Runtime, drei Injectors und drei Anwendungen, die keinen Service teilen.

• Fasse die Widgets eines Teams in einem einzigen Bundle zusammen: ein createApplication(), mehrere define()-Aufrufe.
• Stabile Namen für die Einbindung per <script src>: --output-hashing=none und versionierte Ordner (/1.4.0/main.js), damit du einen langen Cache ohne Hash im Namen nutzen kannst.
• Lazy im Inneren: @defer und import() funktionieren auch innerhalb eines Elements, sodass der schwere Teil des Widgets erst bei Bedarf kommen kann.

# ein eigenes Projekt im Workspace, nur für Widgets
ng generate application atlas-widgets --ssr=false
# main.ts: createApplication + customElements.define (siehe main.ts oben)

# stabile Dateinamen, damit ein CMS <script src=".../main.js">
ng build atlas-widgets --output-hashing=none
# → in versionierte Ordner veröffentlichen: /atlas-widgets/1.4.0/main.js
#   (langer Cache, kein Hash im Namen; die Lazy-Chunks behalten ihren Hash)

# gemessen mit Angular 22.2.2, ein einfaches Element, zoneless, Production-Build:
#   main.js ≈ 110 kB minifiziert, ≈ 33 kB Transfer laut CLI-Schätzung
# jedes separat gebaute Bundle bringt seine eigene Kopie von
# @angular/core + @angular/platform-browser

Verwendung aus anderen Umgebungen

Für statisches HTML genügen ein <script type="module"> und der Tag. Jede der anderen Umgebungen hat ein kleines Konfigurationsdetail:

• Angular: Die Host-Komponente deklariert schemas: [CUSTOM_ELEMENTS_SCHEMA]. Die Bindings [prop] und (event) funktionieren, aber ohne Typprüfung — bist du in derselben Anwendung, nutze die Komponente direkt.
• React 19 unterstützt Custom Elements vollständig: Props, die zu einer Property des Elements passen, werden als DOM-Properties gesetzt (in früheren Versionen kamen sie als Attribute an). Für Custom Events ist die portable Variante ein ref + addEventListener.
• Vue 3 muss wissen, dass der Tag keine Vue-Komponente ist: die Compile-Option isCustomElement.
• CMSs: Der Editor fügt nur HTML ein, also muss sich alles über String-Attribute konfigurieren lassen. Entwirf die Inputs als Primitive; für komplexe Konfigurationen nimmst du ein JSON-Attribut mit einem Transform, der JSON.parse aufruft.

// Ein Custom Element (dein eigenes oder das eines anderen Teams) in einer Angular-Komponente verwenden
import { CUSTOM_ELEMENTS_SCHEMA, Component, signal } from '@angular/core';

@Component({
  selector: 'app-product',
  // ohne das Schema: Fehler „'atlas-rating' is not a known element“
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <atlas-rating
      [value]="rating()"
      max-stars="5"
      (ratingChange)="rating.set($any($event).detail.value)"
    ></atlas-rating>
  `,
})
export class Product {
  protected readonly rating = signal(4);
}
// [value] setzt die DOM-Property, (ratingChange) macht addEventListener —
// aber ganz ohne Typprüfung.

Der Inhalt eines Custom Elements erscheint erst, nachdem das Skript heruntergeladen und ausgeführt wurde. Für Text, der für SEO oder LCP wesentlich ist (der Seitentitel, der Preis, der Hauptinhalt), ist ein Client-seitiges Widget die falsche Wahl — siehe SSR.

Kommunikation zwischen Anwendungen

Wenn mehrere unabhängige Anwendungen auf derselben Seite leben (Widgets verschiedener Teams, Micro Frontends), teilen sie keinen Injector. Es bleiben die Mechanismen der Plattform, in der Reihenfolge, in der es sich lohnt, sie auszuprobieren:

Ein Bus auf window ist der einfachste Vertrag zwischen Anwendungen auf derselben Seite: Event-Namen mit Präfix (atlas:cart:add), Typen in einem kleinen, versionierten Paket, zwei Funktionen emit/listen. Die klassische Falle: Ein Event ist kein Zustand — eine später gemountete Anwendung hat alles verpasst, was vorher passiert ist. Die Lösung ist ein Handshake — beim Start fragst du den Zustand ab, und sein Besitzer antwortet.

// contracts/atlas-events.ts — ein kleines, versioniertes Paket, das sich die Teams teilen
export interface AtlasEvents {
  'atlas:cart:add': { sku: string; qty: number };
  'atlas:cart:changed': { count: number; total: number };
  'atlas:cart:state-request': { from: string };
}

export function emit<K extends keyof AtlasEvents>(type: K, detail: AtlasEvents[K]): void {
  window.dispatchEvent(new CustomEvent(type, { detail }));
}

export function listen<K extends keyof AtlasEvents>(
  type: K,
  fn: (detail: AtlasEvents[K]) => void,
): () => void {
  const handler = (e: Event) => fn((e as CustomEvent<AtlasEvents[K]>).detail);
  window.addEventListener(type, handler);
  return () => window.removeEventListener(type, handler);
}

BroadcastChannel verbindet alle Kontexte derselben Origin, die einen Kanal mit demselben Namen öffnen: Tabs, Fenster, iframes, Worker. Die Nachricht wird per Structured Clone kopiert (keine Funktionen, keine Klasseninstanzen mit Methoden) und erreicht das Objekt nicht, das sie gesendet hat. Typische Einsätze: Logout in allen Tabs, Synchronisieren des Warenkorbs, Invalidieren eines Caches. Für iframes anderer Origin bleibt postMessage, mit an beiden Enden geprüfter Origin.

// Gleiche Origin: andere Tabs, Fenster, iframes, Worker
@Injectable({ providedIn: 'root' })
export class SessionSync {
  private readonly channel = new BroadcastChannel('atlas-session');
  private readonly router = inject(Router);

  constructor() {
    this.channel.onmessage = (e: MessageEvent<{ type: 'logout' }>) => {
      if (e.data?.type === 'logout') this.router.navigateByUrl('/login');
    };
    inject(DestroyRef).onDestroy(() => this.channel.close());
  }

  logoutEverywhere(): void {
    // erreicht die anderen Tabs, NICHT dieses Objekt
    this.channel.postMessage({ type: 'logout' });
  }
}

Wann ja, wann nein

Häufige Stolperfallen

• Der Selektor der Komponente als Tag verwendet → zwei Instanzen auf demselben Element. Nimm einen separaten Selektor (atlas-rating-cmp).
• define() zweimal aufgerufen (HMR, Tests, zwei Bundles, die denselben Tag definieren) → NotSupportedError. Prüfe customElements.get(); zwischen Teams versiehst du die Tags mit dem Produktnamen als Präfix.
• Erwarten, dass Events nach oben bubbeln → ein Listener auf document, der nichts empfängt. Höre am Element zu oder sende explizit neu mit bubbles: true, composed: true.
• Outputs mit den Namen change, input, click → sie vermischen sich mit den nativen Events der inneren Elemente, die den Host erreichen. Nimm spezifische Namen (ratingChange).
• Ein numerischer Input ohne Transform → das Attribut kommt als String an, und aus maxStars() + 1 wird '71'. Setze numberAttribute / booleanAttribute auf jeden Input, der sich aus HTML konfigurieren lässt.
• Objekte über Attribute → die Komponente erhält "[object Object]". Sende Objekte und Arrays als Properties.
• Erwarten, dass das Element die Services der übergeordneten Komponente sieht → es nutzt den Injector, der an createCustomElement übergeben wurde, nicht die Stelle im DOM, an die du es gesetzt hast. Services aus den providers einer Komponente oder einer Route erreichen es nicht.
• Nach dem Erzeugen hinzugefügte Kinder → die Knoten für <ng-content> werden nur einmal beim Verbinden eingesammelt. Dynamischer Inhalt wird über Properties gesendet.
• Ein zerstörtes Element wiederverwenden → totes HTML, NG0953, dann NotSupportedError. Erzeuge ein neues Element.
• Nicht geschlossene Listener und Kanäle → nach jedem Mounten ein weiterer window.addEventListener oder ein weiterer offener BroadcastChannel. Räume in DestroyRef.onDestroy auf.
• postMessage(data, '*') und keine Prüfung von event.origin → jede Seite, die dich in einem iframe einbettet, kann Nachrichten lesen oder senden. Siehe Sicherheit.

Spickzettel

// 1. Die Komponente: Inputs mit Transform für Attribute, Outputs mit spezifischen Namen
readonly maxStars = input(5, { transform: numberAttribute }); // <x max-stars="7">
readonly ratingChange = output<RatingChange>();               // CustomEvent, detail

// 2. Definition: nur einmal, Tag ≠ Selektor, Tag mit Bindestrich
createApplication({ providers: [] }).then(({ injector }) => { // eigenes Bundle
  // (in einer bestehenden Anwendung: const injector = inject(ApplicationRef).injector)
  if (!customElements.get('atlas-rating')) {
    customElements.define('atlas-rating', createCustomElement(AtlasRating, { injector }));
  }
});

// 3. Verwendung
el.setAttribute('max-stars', '7');       // string → transform
el.maxStars = 7;                         // beliebiger Typ
el.addEventListener('ratingChange', fn); // am Element: bubbles false, composed false

// 4. Lifecycle: append = create (synchron); remove = destroy nach 10 ms;
//    zerstörte Instanz nicht erneut anhängen → ein anderes Element erzeugen

// 5. Styles: ViewEncapsulation.ShadowDom + CSS-Variablen + ::part() fürs Theming

// 6. Kommunikation: Attribute/Properties/Events → CustomEvent auf window (typisiert)
//    → BroadcastChannel (Tabs, gleiche Origin) → postMessage + Origin (iframes)