@angular/elements
Advanced tools
@angular/elements allows Angular components to be used as custom elements (web components). This enables the integration of Angular components into non-Angular applications and enhances reusability across different frameworks and libraries.
Creating a Custom Element
This code demonstrates how to create a custom element from an Angular component. The `createCustomElement` function is used to convert `MyComponent` into a custom element named 'my-element'.
import { Injector, NgModule } from '@angular/core';
import { createCustomElement } from '@angular/elements';
import { BrowserModule } from '@angular/platform-browser';
import { MyComponent } from './my-component.component';
@NgModule({
declarations: [MyComponent],
imports: [BrowserModule],
entryComponents: [MyComponent]
})
export class AppModule {
constructor(private injector: Injector) {
const myElement = createCustomElement(MyComponent, { injector });
customElements.define('my-element', myElement);
}
ngDoBootstrap() {}
}Using the Custom Element in HTML
Once the Angular component is converted into a custom element, it can be used in any HTML file just like a standard HTML element. This example shows how to include and use the custom element 'my-element' in an HTML file.
<!DOCTYPE html>
<html>
<head>
<title>Angular Element</title>
<script src="path/to/your/angular-element.js"></script>
</head>
<body>
<my-element></my-element>
</body>
</html>Stencil is a compiler that generates Web Components (custom elements) and builds high-performance web apps. It is framework-agnostic and can be used to create reusable components that work with any major framework or no framework at all. Compared to @angular/elements, Stencil is more focused on performance and offers additional features like lazy loading and pre-rendering.
Lit is a simple library for building fast, lightweight web components. It provides a minimal API to define custom elements and manage their lifecycle. Lit is known for its small size and ease of use, making it a good alternative to @angular/elements for projects that require lightweight and fast custom elements.
vue-custom-element is a Vue plugin that enables the creation of custom elements from Vue components. It allows Vue components to be used as web components in non-Vue applications. This package is similar to @angular/elements but is tailored for Vue.js, providing a seamless way to integrate Vue components as custom elements.
The sources for this package are in the main Angular repo. Please file issues and pull requests against that repo.
Usage information and reference details can be found in Angular documentation.
License: MIT
18.0.0 (2024-05-22)
Blog post "Angular v18 is now available".
matchesElement method has been removed from AnimationDriver as it is unused.isPlatformWorkerUi and isPlatformWorkerApp have been removed without replacement, as they serve no purpose since the removal of the WebWorker platform.OnPush views at the root of the application need to
be marked dirty for their host bindings to refresh. Previously, the host
bindings were refreshed for all root views without respecting the
OnPush change detection strategy.
OnPush views at the root of the application need to
be marked dirty for their host bindings to refresh. Previously, the host
bindings were refreshed for all root views without respecting the
OnPush change detection strategy.
The ComponentFixture autoDetect feature will no
longer refresh the component's host view when the component is OnPush
and not marked dirty. This exposes existing issues in components which
claim to be OnPush but do not correctly call markForCheck when they
need to be refreshed. If this change causes test failures, the easiest
fix is to change the component to ChangeDetectionStrategy.Default.
ComponentFixture.whenStable now matches the
ApplicationRef.isStable observable. Prior to this change, stability
of the fixture did not include everything that was considered in
ApplicationRef. whenStable of the fixture will now include unfinished
router navigations and unfinished HttpClient requests. This will cause
tests that await the whenStable promise to time out when there are
incomplete requests. To fix this, remove the whenStable,
instead wait for another condition, or ensure HttpTestingController
mocks responses for all requests. Try adding HttpTestingController.verify()
before your await fixture.whenStable to identify the open requests.
Also, make sure your tests wait for the stability promise. We found many
examples of tests that did not, meaning the expectations did not execute
within the test body.
In addition, ComponentFixture.isStable would synchronously switch to
true in some scenarios but will now always be asynchronous.
Angular will ensure change detection runs, even when the state update originates from outside the zone, tests may observe additional rounds of change detection compared to the previous behavior.
This change will be more likely to impact existing unit tests.
This should usually be seen as more correct and the test should be updated,
but in cases where it is too much effort to debug, the test can revert to the old behavior by adding
provideZoneChangeDetection({schedulingMode: NgZoneSchedulingMode.NgZoneOnly})
to the TestBed providers.
Similarly, applications which may want to update state outside the zone
and not trigger change detection can add
provideZoneChangeDetection({schedulingMode: NgZoneSchedulingMode.NgZoneOnly})
to the providers in bootstrapApplication or add
schedulingMode: NgZoneSchedulingMode.NgZoneOnly to the
BootstrapOptions of bootstrapModule.
When Angular runs change detection, it will continue to
refresh any views attached to ApplicationRef that are still marked for
check after one round completes. In rare cases, this can result in infinite
loops when certain patterns continue to mark views for check using
ChangeDetectorRef.detectChanges. This will be surfaced as a runtime
error with the NG0103 code.
async has been removed, use waitForAsync instead.
The ComponentFixture.autoDetect feature now executes
change detection for the fixture within ApplicationRef.tick. This more
closely matches the behavior of how a component would refresh in
production. The order of component refresh in tests may be slightly
affected as a result, especially when dealing with additional components
attached to the application, such as dialogs. Tests sensitive to this
type of change (such as screenshot tests) may need to be updated.
Concretely, this change means that the component will refresh before
additional views attached to ApplicationRef (i.e. dialog components).
Prior to this change, the fixture component would refresh after other
views attached to the application.
The exact timing of change detection execution when
using event or run coalescing with NgZone is now the first of either
setTimeout or requestAnimationFrame. Code which relies on this
timing (usually by accident) will need to be adjusted. If a callback
needs to execute after change detection, we recommend afterNextRender
instead of something like setTimeout.
Newly created and views marked for check and reattached
during change detection are now guaranteed to be refreshed in that same
change detection cycle. Previously, if they were attached at a location
in the view tree that was already checked, they would either throw
ExpressionChangedAfterItHasBeenCheckedError or not be refreshed until
some future round of change detection. In rare circumstances, this
correction can cause issues. We identified one instance that relied on
the previous behavior by reading a value on initialization which was
queued to be updated in a microtask instead of being available in the
current change detection round. The component only read this value during
initialization and did not read it again after the microtask updated it.
Testability methods increasePendingRequestCount,
decreasePendingRequestCount and getPendingRequestCount have been
removed. This information is tracked with zones.
By default we now prevent caching of HTTP requests that require authorization . To opt-out from this behaviour use the includeRequestsWithAuthHeaders option in withHttpTransferCache.
Example:
withHttpTransferCache({
includeRequestsWithAuthHeaders: true,
})
StateKey, TransferState and makeStateKey have been removed from @angular/platform-browser, use the same APIs from @angular/core.RESOURCE_CACHE_PROVIDER APIs have been removed.deprecated platformDynamicServer has been removed. Add an import @angular/compiler and replace the usage with platformServer
deprecated ServerTransferStateModule has been removed. TransferState can be use without providing this module.
deprecated useAbsoluteUrl and baseUrl been removed from PlatformConfig. Provide and absolute url instead.
Legacy handling or Node.js URL parsing has been removed from ServerPlatformLocation.
The main differences are;
pathname is always suffixed with a /.port is empty when http: protocol and port in url is 80port is empty when https: protocol and port in url is 443RedirectCommand for redirects
in addition to UrlTree. Code which expects only boolean or UrlTree
values in Route types will need to be adjusted.Route.redirectTo to be a function
in addition to the previous string. Code which expects redirectTo to
only be a string on Route objects will need to be adjusted.UrlTree as a redirect, the
redirecting navigation will now use replaceUrl if the initial
navigation was also using the replaceUrl option. If this is not
desirable, the redirect can configure new NavigationBehaviorOptions by
returning a RedirectCommand with the desired options instead of UrlTree.RouterOutlet. This means that providers available only to the
component that defines the RouterOutlet will no longer be available to
route components in any circumstances. This was already the case
whenever routes defined providers, either through lazy loading an
NgModule or through explicit providers on the route config.RouterOutlet. This means that providers available only to the
component that defines the RouterOutlet will no longer be available to
route components in any circumstances. This was already the case
whenever routes defined providers, either through lazy loading an
NgModule or through explicit providers on the route config.getCurrencySymbol, getLocaleCurrencyCode, getLocaleCurrencyName, getLocaleCurrencySymbol, getLocaleDateFormat, getLocaleDateTimeFormat, getLocaleDayNames, getLocaleDayPeriods, getLocaleDirection, getLocaleEraNames, getLocaleExtraDayPeriodRules, getLocaleExtraDayPeriods, getLocaleFirstDayOfWeek, getLocaleId, getLocaleMonthNames, getLocaleNumberFormat, getLocaleNumberSymbol, getLocalePluralCase, getLocaleTimeFormat, getLocaleWeekEndRange, getNumberOfCurrencyDigits@Component.interpolation is deprecated. Use Angular's
delimiters instead.HttpClientModule, HttpClientXsrfModule and HttpClientJsonpModule
As mentionned, those modules can be replaced by provider function only.
| Commit | Type | Description |
| -- | -- | -- |
| bcce85af72 | refactor | remove deprecated matchesElement from AnimationDriver (#55479) |
| Commit | Type | Description |
| -- | -- | -- |
| d34c033902 | refactor | Deprecate Local Data API functions (#54483) |
| 3b0de30b37 | refactor | remove deprecated isPlatformWorkerApp and isPlatformWorkerUi API (#55302) |
| Commit | Type | Description |
| -- | -- | -- |
| 91b007e58f | fix | add math elements to schema (#55631) |
| 33d0102304 | fix | allow comments between connected blocks (#55966) |
| 7fc7f3f05f | fix | capture all control flow branches for content projection in if blocks (#54921) |
| a369f43fbd | fix | capture switch block cases for content projection (#54921) |
| eb625d3783 | fix | declare for loop aliases in addition to new name (#54942) |
| f824911510 | fix | For FatalDiagnosticError, hide the message field without affecting the emit (#55160) |
| a040fb720a | fix | maintain multiline CSS selectors during CSS scoping (#55509) |
| 39624c6b12 | fix | output input flags as a literal (#55215) |
| eba92cfa55 | fix | prevent usage of reserved control flow symbol in custom interpolation context. (#55809) |
| 7d5bc1c628 | fix | remove container index from conditional instruction (#55190) |
| 4eb0165750 | fix | remove support for unassignable expressions in two-way bindings (#55342) |
| e1650e3b13 | fix | throw error if item name and context variables conflict (#55045) |
| Commit | Type | Description |
| -- | -- | -- |
| 5bd188a394 | feat | add partial compilation support for deferred blocks (#54908) |
| b02b31a915 | feat | drop support for TypeScript older than 5.4 (#54961) |
| 78188e877a | fix | add diagnostic if initializer API is used outside of an initializer (#54993) |
| 69a83993b3 | fix | do not throw when retrieving TCB symbol for signal input with restricted access (#55774) |
| 4f4f41016e | fix | dom property binding check in signal extended diagnostic (#54324) |
| 7a16d7e969 | fix | don't type check the bodies of control flow nodes in basic mode (#55360) |
| 8d93597a82 | fix | fix type narrowing of @if with aliases (#55835) |
| 9b424d7224 | fix | preserve original reference to non-deferrable dependency (#54759) |
| 694ba79cbf | fix | report cases where initializer APIs are used in a non-directive class (#54993) |
| 6219341d26 | fix | report errors when initializer APIs are used on private fields (#54981) |
| c04ffb1fa6 | fix | use switch statements to narrow Angular switch blocks (#55168) |
| Commit | Type | Description |
| -- | -- | -- |
| a730f09ae9 | feat | Add a public API to establish events to be replayed and an attribute to mark an element with an event handler. (#55356) |
| fdd560ea14 | feat | Add ability to configure zone change detection to use zoneless scheduler (#55252) |
| bce5e2344f | feat | Add build target for jsaction contract binary. (#55319) |
| 666d646575 | feat | Add event delegation library to queue up events and replay them when the application is ready (#55121) |
| 5f06ca8f55 | feat | add HOST_TAG_NAME token (#54751) |
| a600a39d0c | feat | add support for fallback content in ng-content (#54854) |
| 146306a141 | feat | add support for i18n hydration (#54823) |
| f09c5a7bc4 | feat | Add zoneless change detection provider as experimental (#55329) |
| d28614b90e | feat | Modify EventType from an enum to an object. (#55323) |
| ac863ded48 | feat | provide ExperimentalPendingTasks API (#55487) |
| 1ee9f32621 | feat | Synchronize changes from internal JSAction codebase. (#55182) |
| d888da4606 | fix | ApplicationRef.tick should respect OnPush for host bindings (#53718) |
| 64f870c12b | fix | ApplicationRef.tick should respect OnPush for host bindings (#53718) (#53718) |
| 8cad4e8cbe | fix | ComponentFixture autoDetect respects OnPush flag of host view (#54824) |
| 658cf8c384 | fix | ComponentFixture stability should match ApplicationRef (#54949) |
| 2fc11eae9e | fix | account for re-projected ng-content elements with fallback content (#54854) |
| 0cbd73c6e9 | fix | add warning when using zoneless but zone.js is still loaded (#55769) |
| d5edfde6ee | fix | afterRender hooks registered outside change detection can mark views dirty (#55623) |
| de7447d15e | fix | Angular should not ignore changes that happen outside the zone (#55102) |
| ba8e465974 | fix | Change Detection will continue to refresh views while marked for check (#54734) |
| 5a10f405d3 | fix | complete the removal of deprecation async function (#55491) |
| 24bc0ed4f2 | fix | ComponentFixture autodetect should detect changes within ApplicationRef.tick (#54733) |
| 1c0ec56c46 | fix | correctly project single-root content inside control flow (#54921) |
| 840c375255 | fix | do not save point-in-time setTimeout and rAF references (#55124) |
| 10c5cdb49c | fix | ensure change detection runs in a reasonable timeframe with zone coalescing (#54578) |
| ad045efd4b | fix | Ensure views marked for check are refreshed during change detection (#54735) |
| 69085ea26e | fix | error about provideExperimentalCheckNoChangesForDebug uses wrong name (#55824) |
| 0147e0b85a | fix | exhaustive checkNoChanges should only do a single pass (#55839) |
| e02bcf89cf | fix | Fix clearing of pending task in zoneless cleanup implementation (#55074) |
| 0cec9e4f9a | fix | Fix null dereference error addEvent (#55353) |
| 44c0ed83a6 | fix | hide implementation details of ExperimentalPendingTasks (#55516) |
| 314112de99 | fix | Prevent markForCheck during change detection from causing infinite loops (#54900) |
| a5fa279b6e | fix | prevent i18n hydration from cleaning projected nodes (#54823) |
| 6534c035c0 | fix | Remove deprecated Testability methods (#53768) |
| a5c57c7484 | fix | resolve error for multiple component instances that use fallback content (#55478) |
| f44a5e4604 | fix | support content projection and VCRs in i18n (#54823) |
| 0510930a25 | fix | TestBed should not override NgZone from initTestEnvironment (#55226) |
| e9a0c86766 | fix | TestBed should not override NgZone from initTestEnvironment (#55226) |
| 700c0520bb | fix | Update ApplicationRef.tick loop to only throw in dev mode (#54848) |
| a99cb7ce5b | fix | zoneless scheduler should check if Zone is defined before accessing it (#55118) |
| 1fd63e9cff | refactor | deprecate @Component.interpolation (#55778) |
| Commit | Type | Description | | -- | -- | -- | | 1c736dc3b2 | feat | Unified Control State Change Events (#54579) | | 61007dced0 | fix | Add event for forms submitted & reset (#55667) | | 2e27ca9ddf | fix | Allow canceled async validators to emit. (#55134) |
| Commit | Type | Description |
| -- | -- | -- |
| 6f88d80758 | feat | allow caching requests with different origins between server and client (#55274) |
| 8eacb6e4b9 | feat | exclude caching for authenticated HTTP requests (#55034) |
| d9b339fdbc | fix | resolve withRequestsMadeViaParent behavior with withFetch (#55652) |
| ef665a40a5 | refactor | Deprecate HttpClientModule & related modules (#54020) |
| Commit | Type | Description | | -- | -- | -- | | 6d1b82df32 | fix | allow external projects to use provided compiler options (#55035) | | a48afe0d94 | fix | avoid generating TS syntactic diagnostics for templates (#55091) | | bd236cc150 | fix | implement getDefinitionAtPosition for Angular templates (#55269) | | 4166dfc1b6 | fix | prevent underlying TS Service from handling template files (#55003) | | b7f2fd4739 | fix | use type-only import in plugin factory (#55996) |
| Commit | Type | Description |
| -- | -- | -- |
| f914f6a362 | feat | Migration schematics for HttpClientModule (#54020) |
| 8459ee46cb | fix | handle more cases in HttpClientModule migration (#55640) |
| c4b2f18709 | fix | migrate HttpClientTestingModule in test modules (#55803) |
| bb4a4016a9 | fix | preserve existing properties in HttpClientModule migration (#55777) |
| f93e5180be | fix | resolve multiple structural issues with HttpClient migration (#55557) |
| Commit | Type | Description | | -- | -- | -- | | 45ae7a6b60 | feat | add withI18nSupport() in developer preview (#55130) | | 23f914f101 | fix | Use the right namespace for mathML. (#55622) | | cba336d4f1 | refactor | remove deprecated transfer state APIs (#55474) |
| Commit | Type | Description |
| -- | -- | -- |
| eb20c1a8b1 | refactor | unused RESOURCE_CACHE_PROVIDER API has been removed (#54875) |
| Commit | Type | Description |
| -- | -- | -- |
| 5674c644ab | fix | add nonce attribute to event record script (#55495) |
| e71e869112 | fix | remove event dispatch script from HTML when hydration is disabled (#55681) |
| 07ac017731 | refactor | remove deprecated platformDynamicServer API (#54874) |
| e8b588d8b7 | refactor | remove deprecated ServerTransferStateModule API (#54874) |
| 3b1967ca64 | refactor | remove deprecated useAbsoluteUrl and baseUrl from PlatformConfig (#54874) |
| 2357d3566c | refactor | remove legacy URL handling logic (#54874) |
| Commit | Type | Description |
| -- | -- | -- |
| 4a42961393 | feat | withNavigationErrorHandler can convert errors to redirects (#55370) |
| 8735af08b9 | feat | Add ability to return UrlTree with NavigationBehaviorOptions from guards (#45023) |
| 87f3f27f90 | feat | Allow resolvers to return RedirectCommand (#54556) |
| 2b802587f2 | feat | Allow Route.redirectTo to be a function which returns a string or UrlTree (#52606) |
| 60f1d681e0 | fix | preserve replaceUrl when returning a urlTree from CanActivate (#54042) |
| 3839cfbb18 | fix | Routed components never inherit RouterOutlet EnvironmentInjector (#54265) |
| da906fdafc | fix | Routed components never inherit RouterOutlet EnvironmentInjector (#54265) |
| Commit | Type | Description |
| -- | -- | -- |
| 3bc63eaaf3 | fix | avoid running CDs on controllerchange (#54222) |
| e598634c10 | fix | remove controllerchange listener when app is destroyed (#55365) |
<a name="17.3.9"></a>
FAQs
Angular - library for using Angular Components as Custom Elements
The npm package @angular/elements receives a total of 303,093 weekly downloads. As such, @angular/elements popularity was classified as popular.
We found that @angular/elements demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.