Angular Elements

Relevant source files

Angular Elements provides the capability to package Angular components as custom elements (web components) that can be used in any HTML document, regardless of the framework. This allows Angular components to be consumed in non-Angular applications, server-rendered pages, or any context where standard HTML elements are used.

For information about creating standard Angular components, see Core Runtime Architecture. For server-side rendering, see Server-Side Rendering. For general security considerations when building web components, see Content Security and Sanitization.

Purpose and Architecture

Angular Elements bridges Angular's component model with the Web Components standard by transforming Angular components into browser-native custom elements. The transformation wraps Angular's dependency injection, change detection, and rendering infrastructure into a custom element that can be instantiated using standard DOM APIs.

Architecture Overview

Sources: adev/src/content/guide/elements.md1-169

Package Structure and Core APIs

The @angular/elements package exports several key types and functions for creating and managing custom elements.

Core Package Exports

Key Functions and Types:

Symbol	Type	Purpose
`createCustomElement()`	Function	Converts an Angular component into a constructor class for custom elements
`NgElement`	Interface	Type representing a custom element created from an Angular component
`WithProperties<T>`	Type	Helper type that adds component properties to NgElement
`NgElementConstructor`	Interface	Constructor interface returned by createCustomElement
`NgElementStrategy`	Interface	Internal strategy for managing component lifecycle

Sources: adev/src/content/guide/elements.md36-62 adev/src/content/guide/elements.md104-162

Component Transformation Process

The transformation from an Angular component to a custom element follows a specific process that involves metadata extraction, constructor creation, and registration with the browser.

Transformation Pipeline

Implementation Steps:

Component Analysis: The createCustomElement() function inspects the component's metadata to identify input properties and output events
Attribute Mapping: Input property names are transformed to dash-separated lowercase attribute names. Property aliases (from @Input({alias: 'name'})) are respected
Event Mapping: Output properties become Custom Events with the output name (or alias) as the event type
Constructor Generation: An NgElementConstructor is created that implements the custom element lifecycle callbacks
Registration: The generated constructor is registered with the browser using customElements.define()

Sources: adev/src/content/guide/elements.md49-78

Property and Event Mapping

Angular Elements automatically maps component properties and events to Web Components standards.

Input Property Mapping

Output Event Mapping

Naming Conventions:

Component Feature	Custom Element Equivalent	Example
`@Input() prop`	`prop` attribute (dash-case)	`inputValue` → `input-value`
`@Input({alias: 'x'}) prop`	`x` attribute (dash-case)	`myProp` → `my-prop`
`@Output() event`	`CustomEvent` with type name	`valueChanged` → `valueChanged` event
`@Output({alias: 'x'}) event`	`CustomEvent` with alias	`myClick` → `myClick` event

Sources: adev/src/content/guide/elements.md63-78

Lifecycle and Bootstrapping

Custom elements created with Angular Elements manage their own lifecycle and automatically bootstrap Angular's runtime infrastructure when attached to the DOM.

Custom Element Lifecycle

Self-Bootstrapping Behavior:

Custom elements created with Angular Elements are self-bootstrapping:

They start automatically when added to the DOM
They destroy themselves when removed from the DOM
No Angular-specific initialization is required by the host application
Each custom element instance maintains its own Angular component instance

Sources: adev/src/content/guide/elements.md14-18

The Angular documentation includes a complete example demonstrating both traditional dynamic component loading and the custom elements approach.

Popup Service Architecture

Key Implementation Differences:

The traditional dynamic component loading approach (popup.service.ts18-42):

Requires explicit createComponent() call
Must manually attach to ApplicationRef
Needs to wire up component properties manually
Requires explicit cleanup on destruction

The custom element approach (popup.service.ts44-59):

Uses standard DOM API document.createElement()
Properties set directly on the element
Events handled with standard addEventListener()
Automatic cleanup when removed from DOM

Type Safety with Custom Elements:

Sources: adev/src/content/examples/elements/src/app/popup.service.ts1-61 adev/src/content/guide/elements.md79-102

Type System Integration

Angular Elements provides TypeScript types to enable type-safe interactions with custom elements.

Type Augmentation Pattern:

The WithProperties and NgElement types allow TypeScript to understand custom element properties:

Type Hierarchy:

Type	Extends	Purpose
`NgElement`	`HTMLElement`	Base interface for Angular-created custom elements
`WithProperties<T>`	`NgElement`	Adds component-specific properties to NgElement
`HTMLElementTagNameMap`	Native interface	Browser's type mapping for element tag names

When HTMLElementTagNameMap is augmented, TypeScript automatically provides correct types for:

document.createElement('my-dialog') returns the correct type
document.querySelector('my-dialog') returns the correct type
Property access is type-checked
IDE autocomplete works for component properties

Sources: adev/src/content/guide/elements.md104-162

Registration and Usage Pattern

Bootstrap Configuration:

Important Considerations:

The component's selector should not be used as the custom element tag name. Using the same name can cause Angular to create two component instances for a single DOM element:

One regular Angular component (from the selector match)
One custom element wrapper (from the custom element definition)

Sources: adev/src/content/guide/elements.md59-62 adev/src/content/guide/elements.md86-102

Limitations and Known Issues

Angular Elements has specific limitations related to the browser's custom element lifecycle:

Known Issues:

Issue	Description	Affected Scenarios
`disconnect()` callback	Problems with custom element disconnect behavior	Destroying and re-attaching elements
AngularJS integration	Issues when rendering in `ng-if` or `ng-repeat`	Hybrid AngularJS/Angular applications
Manual DOM manipulation	Detaching and re-attaching can cause issues	Dynamic DOM operations

Recommended Practices:

Avoid destroying and re-attaching custom elements when possible
If dynamic visibility is needed, use CSS display or visibility properties instead of removing from DOM
Test thoroughly when integrating with AngularJS or other frameworks that manipulate the DOM
Be aware that the custom element lifecycle is controlled by the browser, not Angular

Sources: adev/src/content/guide/elements.md163-169

Integration with Angular Ecosystem

Dependencies on Core Angular Systems:

Angular Elements relies on several core Angular systems:

System	Role in Angular Elements
Dependency Injection	Provides services to custom element components (guide/di)
Change Detection	Triggers updates when properties change (guide/change-detection)
Renderer	Performs DOM updates for the component (guide/rendering)
Compiler	Compiles component templates (must use AOT for production) (compiler)

Security Considerations:

Custom elements inherit Angular's security model:

Template bindings are sanitized automatically
Content Security Policy applies to inline styles
XSS protection applies to dynamic content

For detailed security considerations, see Content Security and Sanitization.

Sources: adev/src/content/guide/elements.md1-169 adev/src/content/guide/security.md1-370