Angular Elements

Browser visits page    ↓Angular's bootstrapApplication() creates the root injector + app tree    ↓<app-root> component is instantiated by Angular    ↓Child components instantiated, DI resolved, lifecycle hooks called    ↓Zone.js or signals schedule CD cycles

// Any JS (not Angular-specific) can register a custom elementclass MyElement extends HTMLElement {  connectedCallback() { /* tag added to DOM */ }  disconnectedCallback() { /* tag removed from DOM */ }}customElements.define('my-element', MyElement);
// Browser now handles <my-element> like <div> or <span>

Browser encounters <rating-widget stars="4">    ↓customElements callback fires (browser native)    ↓createCustomElement wrapper:  - Creates Angular injector (or reuses app-level one)  - Boots the RatingWidgetComponent  - Connects inputs (stars="4" → @Input() stars)  - Listens for @Output() EventEmitters → dispatches DOM CustomEvents    ↓Angular CD + lifecycle hooks run normally    ↓When <rating-widget> is removed from DOM:  ngOnDestroy called, subscriptions cleaned up

ng add @angular/elements

// main.tsimport { createApplication } from '@angular/platform-browser';import { provideHttpClient } from '@angular/common/http';import { createCustomElement } from '@angular/elements';import { RatingWidgetComponent } from './app/rating-widget.component';import { TooltipComponent } from './app/tooltip.component';
(async () => {  // Create a minimal Angular application — no root component  const app = await createApplication({    providers: [      provideHttpClient(),          // shared services for all custom elements    ],  });
  // Register one or more custom elements using the shared injector  const RatingElement = createCustomElement(RatingWidgetComponent, {    injector: app.injector,  });  customElements.define('rating-widget', RatingElement);
  const TooltipElement = createCustomElement(TooltipComponent, {    injector: app.injector,  });  customElements.define('app-tooltip', TooltipElement);})();

// app.component.tsimport { Component, Injector, inject } from '@angular/core';import { createCustomElement } from '@angular/elements';import { RatingWidgetComponent } from './rating-widget.component';
@Component({  selector: 'app-root',  standalone: true,  template: `<router-outlet />`,})export class AppComponent {  private injector = inject(Injector);
  constructor() {    // Guard against re-registration (e.g. hot module reload)    if (!customElements.get('rating-widget')) {      const RatingElement = createCustomElement(RatingWidgetComponent, {        injector: this.injector,      });      customElements.define('rating-widget', RatingElement);    }  }}

import { Component, input, output, signal, computed } from '@angular/core';import { ViewEncapsulation } from '@angular/core';
@Component({  selector: 'rating-widget',    // selector matters less — tag name comes from customElements.define  standalone: true,  // ShadowDom gives true CSS isolation — styles can't leak in or out  encapsulation: ViewEncapsulation.ShadowDom,  template: `    <div class="stars">      @for (star of stars; track $index) {        <button          (click)="setRating($index + 1)"          [class.filled]="$index < currentRating()"          aria-label="Rate {{ $index + 1 }} stars"        >★</button>      }    </div>  `,  styles: [`    .stars { display: flex; gap: 4px; }    .filled { color: gold; }    button { border: none; background: none; cursor: pointer; font-size: 1.5rem; }  `],})export class RatingWidgetComponent {  // Signal inputs work — map to attributes  maxStars = input(5);  initialRating = input(0);
  // Outputs map to DOM CustomEvents  rated = output<number>();
  stars = computed(() => Array(this.maxStars()).fill(0));  currentRating = signal(this.initialRating());
  setRating(n: number): void {    this.currentRating.set(n);    this.rated.emit(n);  }}

<!-- Plain HTML page — no Angular knowledge needed --><script src="rating-widget-bundle.js"></script>
<rating-widget max-stars="5" initial-rating="3"></rating-widget>
<script>  const widget = document.querySelector('rating-widget');
  // Read and set inputs via DOM properties  console.log(widget.currentRating); // 3  widget.initialRating = 4;          // set programmatically
  // Listen for outputs as native DOM events  widget.addEventListener('rated', (event) => {    console.log('User rated:', event.detail); // event.detail = the emitted value  });</script>

// React — custom elements are native HTML so React renders them fine// @Output() events become native DOM events — add listener via reffunction ProductPage() {  const widgetRef = useRef(null);
  useEffect(() => {    const el = widgetRef.current;    const handler = (e) => console.log('Rated:', e.detail);    el.addEventListener('rated', handler);    return () => el.removeEventListener('rated', handler);  }, []);
  return <rating-widget max-stars="5" initial-rating="3" ref={widgetRef} />;}

// angular.json — configure a dedicated build target{  "projects": {    "my-elements": {      "targets": {        "build": {          "builder": "@angular-devkit/build-angular:browser-esbuild",          "options": {            "outputHashing": "none",   // predictable filenames            "singleBundle": true       // all in one file          }        }      }    }  }}

ng build my-elements --configuration=production

// ❌ Throws on second call — "DOMException: already defined"customElements.define('my-widget', createCustomElement(MyComponent, { injector }));
// ✅ Guard with customElements.get()if (!customElements.get('my-widget')) {  customElements.define('my-widget', createCustomElement(MyComponent, { injector }));}

// Component input@Input() userName = '';// or: userName = input('');

<!-- ✅ HTML attribute — kebab-case --><my-widget user-name="Alice"></my-widget>
<!-- ❌ HTML attribute — camelCase doesn't work in HTML --><my-widget userName="Alice"></my-widget>

// ✅ JavaScript property — camelCase works on the DOM objectdocument.querySelector('my-widget').userName = 'Alice';

// Component@Output() userSelected = new EventEmitter<User>();

// ❌ event.data is undefinedelement.addEventListener('userSelected', e => console.log(e.data));
// ✅ Emitted value is in event.detailelement.addEventListener('userSelected', e => console.log(e.detail));

// ❌ Default encapsulation — styles can bleed@Component({ encapsulation: ViewEncapsulation.Emulated, ... })
// ✅ Shadow DOM — true isolation; host page styles can't affect internals@Component({ encapsulation: ViewEncapsulation.ShadowDom, ... })