{"id":6497,"date":"2022-09-04T19:47:23","date_gmt":"2022-09-04T17:47:23","guid":{"rendered":"https:\/\/www.angulararchitects.io\/?p=6497"},"modified":"2023-09-04T12:52:58","modified_gmt":"2023-09-04T10:52:58","slug":"angular-elements-web-components-with-standalone-components","status":"publish","type":"post","link":"https:\/\/www.angulararchitects.io\/en\/blog\/angular-elements-web-components-with-standalone-components\/","title":{"rendered":"Angular Elements: Web Components with Standalone Components"},"content":{"rendered":"
\n\t\t\t\n\t\n\t\n\t\t

\n\t\t\tThis is post 5 of 8 in the series “Angular's Future with Standalone Components”<\/em>\t\t<\/p>\n\t\t\t<\/label>\n\n\t\t\t

\n\t\t\t
    \n\t\t\t\t\t\t\t\t\t
  1. Angular’s Future Without NgModules – Part 1: Lightweight Solutions Using Standalone Components<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  2. Angular’s Future Without NgModules – Part 2: What Does That Mean for Our Architecture?<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  3. 4 Ways to Prepare for Angular’s Upcoming Standalone Components<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  4. Routing and Lazy Loading with Angular’s Standalone Components<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  5. Angular Elements: Web Components with Standalone Components<\/span><\/li>\n\t\t\t\t\t\t\t\t\t
  6. The Refurbished HttpClient in Angular 15 – Standalone APIs and Functional Interceptors<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  7. Testing Angular Standalone Components<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  8. Automatic Migration to Standalone Components in 3 Steps<\/a><\/li>\n\t\t\t\t\t\t\t<\/ol>\n\t\t<\/div>\n\t<\/div>\n

    Since Angular 14.2, it\\'s possible to use Standalone Components as Angular Elements. In this article, I\\'m going to show you, how this new feature works.<\/p>\n

    \ud83d\udcc2 Source Code<\/a><\/p>\n

    Providing a Standalone Component<\/h2>\n

    The Standalone Component I\\'m going to use here is a simple Toggle Button called ToggleComponent<\/code>:<\/p>\n

    import { Component, EventEmitter, Input, Output, ViewEncapsulation } from '@angular\/core';\nimport { CommonModule } from '@angular\/common';\n\n@Component({\n  selector: 'app-toggle',\n  standalone: true,\n  imports: [],\n  template: `\n    <div class="toggle" [class.active]="active" (click)="toggle()">\n      <slot>Toggle!<\/slot>\n    <\/div>\n  `,\n  styles: [`\n    .toggle {\n      padding:10px;\n      border: solid black 1px;\n      cursor: pointer;\n      display: inline\n    }\n\n    .active {\n      background-color: lightsteelblue;\n    }\n  `],\n  encapsulation: ViewEncapsulation.ShadowDom\n})\nexport class ToggleComponent {\n\n  @Input() active = false;\n  @Output() change = new EventEmitter<boolean>();\n\n  toggle(): void {\n    this.active = !this.active;\n    this.change.emit(this.active);\n  }\n\n}<\/code><\/pre>\n
    By setting encapsulation to ViewEncapsulation.ShadowDom<\/code>, I\\'m making the browser to use "real" Shadow DOM instead of Angular\\'s emulated counterpart. However, this also means that we have to use the Browser\\'s slot<\/code> API for content projection instead of Angular\\'s ng-content<\/code>.<\/p>\n
    Installing Angular Elements<\/h2>\n
    While Angular Elements is directly provided by the Angular team, the CLI doesn\\'t install it. Hence, we need to do this by hand:<\/p>\n
    npm i @angular\/elements<\/code><\/pre>\n
    In former days, @angular\/elements<\/code> also supported ng add<\/code>. This support came with a schematic for adding a needed polyfill. However, meanwhile, all browsers supported by Angular can deal with Web Components natively. Hence, there is no need for such a polyfill anymore and so the support for ng add<\/code> was already removed some versions ago.<\/p>\n
    Bootstrapping with Angular Elements<\/h2>\n
    Now, let\\'s bootstrap our application and expose the ToggleComponent<\/code> as a Web Component (Custom Element) with Angular Elements. For this, we can use the function createApplication<\/code> added with Angular 14.2:<\/p>\n
    \/\/ main.ts\n\nimport { createCustomElement } from '@angular\/elements';\nimport { createApplication } from '@angular\/platform-browser';\nimport { ToggleComponent } from '.\/app\/toggle\/toggle.component';\n\n(async () => {\n\n  const app = await createApplication({\n    providers: [\n      \/* your global providers here *\/\n    ],\n  });\n\n  const toogleElement = createCustomElement(ToggleComponent, {\n    injector: app.injector,\n  });\n\n  customElements.define('my-toggle', toogleElement);\n\n})();<\/code><\/pre>\n
    We could pass an array with providers to createApplication<\/code>. This allows to provide services like the HttpClient<\/code> via the application\\'s root scope. In general, this option is needed when we want to configure these providers, e. g. with a forRoot<\/code> method or a provideXYZ<\/code> function. In all other cases, it\\'s preferable to just go with tree-shakable providers (providedIn: 'root'<\/code>).<\/p>\n
    The result of createApplication<\/code> is a new ApplicationRef<\/code>. We can pass it\\'s Injector alongside the ToggleComponent<\/code> to createCustomElement<\/code>. The result is a custom element that can be registered with the browser using customElements.define<\/code>.<\/p>\n
    Please note that the current API does not allow for setting an own zone instance like the noop<\/code> zone. Instead, the Angular team wants to concentrate on new features for zone-less change detection in the future.<\/p>\n
    Side Note: Bootstrapping Multiple Components<\/h2>\n
    The API shown also allows to create several custom elements:<\/p>\n
    const element1 = createCustomElement(ThisComponent, {\n    injector: app.injector,\n});\n\nconst element2 = createCustomElement(ThatComponent, {\n    injector: app.injector,\n});<\/code><\/pre>\n
    Besides working with custom elements, the ApplicationRef<\/code> at hand also allows for bootstrapping several components as Angular applications:<\/p>\n
    app.injector.get(NgZone).run(() => {\n    app.bootstrap(ToggleComponent, 'my-a');\n    app.bootstrap(ToggleComponent, 'my-b');\n});<\/code><\/pre>\n
    When bootstrapping a component this way, one can overwrite the selector to use. Please note, that one has to call bootstrap<\/code> within a zone in order to get change detection.<\/p>\n
    Bootstrapping several components was originally done by placing several components in your AppModule<\/code>\\'s bootstrap<\/code> array. The bootstrapApplication<\/code> function used for bootstrapping Standalone Components does, however, not allow for this as the goal was to provide a simple API for the most common use case.<\/p>\n
    Calling an Angular Element<\/h2>\n
    To call our Angular Element, we just need to place a respective tag in our index.html<\/code>:<\/p>\n
    <h1>Standalone Angular Element Demo<\/h1>\n<my-toggle id="myToggle">Click me!<\/my-toggle><\/code><\/pre>\n
    As a custom element is threaded by the browser as a normal DOM node, we can use traditional DOM calls to set up events and to assign values to properties:<\/p>\n
    <script>\n  const myToggle = document.getElementById('myToggle');\n\n  myToggle.addEventListener('change', (event) => {\n    console.log('active', event.detail);\n  });\n\n  setTimeout(() => {\n    myToggle.active = true; \n  }, 3000);\n<\/script><\/code><\/pre>\n
    Calling a Web Component in an Angular Component<\/h2>\n
    If we call a web component within an Angular component, we can directly data bind to it using brackets for properties and parenthesis for events. This works regardless whether the web component was created with Angular or not.<\/p>\n
    To demonstrate this, let\\'s assume we have the following AppComponent:<\/p>\n
    import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular\/core';\n\n@Component({\n  selector: 'app-root',\n  standalone: true,\n  schemas: [CUSTOM_ELEMENTS_SCHEMA],\n  template: `\n    <h2>Root Component<\/h2>\n    <my-toggle \n        [active]="active" \n        (change)="change($event)">\n        Hello!\n    <\/my-toggle>\n  `,\n})\nexport class AppComponent {\n    active = false;\n    change(event: Event) {\n        const customEvent = event as CustomEvent<boolean>;\n        console.log('active', customEvent.detail);\n    }\n}<\/code><\/pre>\n
    This Standalone Component calls our my-toggle<\/code> web component. While the Angular compiler is aware of all possible Angular components, it doesn\\'t know about web components. Hence, it would throw an error when seeing the my-toggle<\/code> tag. To avoid this, we need to register the CUSTOM_ELEMENTS_SCHEMA<\/code> schema.<\/p>\n
    Before, we did this with all the NgModules we wanted to use together with Web Components. Now, we can directly register this schema with Standalone Components. Technically, this just disables the compiler checks regarding possible tag names. This is binary - the checks are either on or off -- and there is no way to directly tell the compiler about the available web components.<\/p>\n
    To make this component appear on our page, we need to bootstrap it:<\/p>\n
    \/\/ main.ts\n\n[...]\n\/\/ Register web components ...\n[...]\n\napp.injector.get(NgZone).run(() => {\n  app.bootstrap(AppComponent);\n});<\/code><\/pre>\n
    Also, we need to add an element for AppComponent to the index.html:<\/p>\n
    <app-root><\/app-root><\/code><\/pre>\n
    Bonus: Compiling Self-contained Bundle<\/h2>\n
    Now, let\\'s assume, we only provide a custom element and don\\'t bootstrap our AppComponent<\/code>. In order to use this custom element in other applications, we need to compile it into a self contained bundle. While the default webpack-based builder emits several bundles, e. g. a main bundle and a runtime bundle, the new -- still experimental -- esbuild-based one just gives us one bundle for our source code and another one for the polyfills.<\/p>\n
    To activate it, adjust your project settings in your angular.json<\/code> as follows:<\/p>\n
    "build": {\n    "builder": "@angular-devkit\/build-angular:browser-esbuild",\n    [...]\n}<\/code><\/pre>\n
    Normally, you just have to add -esbuild<\/code> at the end of the default builder.<\/p>\n
    The resulting bundles look like this:<\/p>\n
    favicon.ico (948 bytes)\nindex.html (703 bytes)\nmain.43BPAPVS.js (100\u00a0177 bytes)\npolyfills.M7XCYQVG.js (33\u00a0916 bytes)\nstyles.VFXLKGBH.css (0 bytes)<\/code><\/pre>\n
    If you use your web component in an other web site, e. g. a CMS-driven one, just reference the main bundle there and add a respective tag. Also, reference the polyfills. However, when using several such bundles, you have to make sure, you only load the polyfills once.<\/p>\n
    The last listing also shows a tradeoff of Angular Elements: Parts of Angular end up in the bundle. Hence, we have an overhead of some KB per bundle.<\/p>\n
    What\\'s next? More on Architecture!<\/h2>\n
    Standalone Components are quite interesting for our architectures. However, there are also other topics we need to considern:<\/p>\n