@angular/elements

Compiles Angular components to standards-compliant Custom Elements. The smallest public package in the framework (~2,100 lines of TypeScript).

Purpose

@angular/elements lets you ship Angular components into non-Angular hosts (a vanilla JS page, a React app, a CMS template) by registering them as Custom Elements.

Two-API surface:

• createCustomElement(component, {injector}) — wraps a component class as a CustomElementConstructor.
• The runtime adapter that proxies attribute changes, properties, events, and lifecycle to/from the wrapped component.

Directory layout

packages/elements/
├── src/
│   ├── create-custom-element.ts   # createCustomElement entry point
│   ├── component-factory-strategy.ts  # The component → element adapter
│   ├── element-strategy.ts        # Strategy interface for swappable backends
│   └── utils.ts
└── public_api.ts

Key abstractions

Type / function	File	What it is
createCustomElement	packages/elements/src/create-custom-element.ts	The factory: returns a CustomElementConstructor.
NgElementStrategy	packages/elements/src/element-strategy.ts	The adapter contract — connect, disconnect, set inputs, listen for outputs.
ComponentNgElementStrategy	packages/elements/src/component-factory-strategy.ts	The default implementation built on ApplicationRef.bootstrap.

How it works

graph LR
  Component[Angular component class] --> Factory[createCustomElement]
  Factory --> Strategy[ComponentNgElementStrategy]
  Strategy --> Adapter[NgElement subclass]
  Adapter --> Browser[CustomElementRegistry.define]
  Browser --> DOM[Page <my-element> usage]
  DOM --> Adapter
  Adapter --> Strategy
  Strategy --> Component

The adapter intercepts attributeChangedCallback, maps DOM attributes onto component inputs (with type coercion via transform), and re-emits component outputs as DOM CustomEvents.

Integration points

• @angular/core — uses ApplicationRef, Injector, and ComponentRef from core.
• Standalone bootstrap — the recommended pattern is to call createCustomElement against a standalone component and pass the EnvironmentInjector from bootstrapApplication's result.
• Element naming — the consumer is responsible for calling customElements.define(...). The library deliberately doesn't claim names.

Entry points for modification

• A new strategy (e.g., an SSR-friendly one): implement NgElementStrategyFactory and pass it to createCustomElement.
• New attribute-coercion behavior: extend packages/elements/src/utils.ts plus the strategy that consumes it.

The integration test at integration/ng_elements/ is the canonical reproduction harness.