Angular 6 – Use Angular Elements to build Custom Elements example

Custom Element is a web standard with new HTML element which allows us to define a tag whose content is created and controlled by JavaScript code in a framework-agnostic way. Custom Element bootstraps itself. That means it starts automatically when added to the DOM, and is automatically destroyed when removed from the DOM. It looks and behaves like any HTML element without need to know anything about Angular, component’s data structures or implementation. This feature is currently supported by Chrome, Opera, and Safari, and available in other browsers through polyfills. In the tutorial, we will show you way to build a Custom Element from Angular Component using Angular Elements.

Angular Elements

@angular/elements package includes a createCustomElement() function that converts a component into a class that can be registered with the browser as a Custom Element.

After registering configured class with the browser’s custom-element registry, we can use the new element just like a built-in HTML element:

Now our component-defined view with change detection and data binding, mapping Angular functionality automatically connect to the corresponding native HTML equivalents:

– Inside Angular Project:

– Outside Angular Project:

Step by Step

Setup Environment

Install latest Angular CLI

Angular Elements is a new feature of Angular 6. So to use it, we have to get latest Angular CLI to work with this new release.

Run this command: npm install -g @angular/cli@latest.

Install Angular Elements Package

First, create new Angular Project:

Installing @angular/elements is just like a regular npm package, but now, the thing is easier to add elements to our project with new ‘add’ command:

Build Custom Element

Add Angular Component

jsa-counter.component.html

jsa-counter.component.css

Component CSS styles will be encapsulated into the Component’s view and won’t affect the rest of the application.
We can set the view encapsulation mode in the component metadata.

jsa-counter.component.ts

Convert to Custom Element

To do this, inside app.module.ts, follow the steps below:
– Add your component to entryComponents of @NgModule decorator. This will exclude the Component from compilation and avoid startup warnings or errors.
– Implement the ngDoBootstrap() method to manually bootstrap that app. We don’t register a bootstrap component with this module.
– Call createCustomElement() to convert Angular Component (together with its dependencies) to a Custom Element.
– Use customElements.define() JavaScript function to register the configured constructor and its associated custom-element tag with the browser’s CustomElementRegistry.

app.module.ts

Use Custom Element

Inside Angular Project

Add the Custom Element to src/index.html:

Run command ng serve or npm start.
Open browser with url http://localhost:4200/:

Outside Angular Project

These things should be done:
– build production including runtime.js, polyfills.js, scripts.js and main.js
– concatenate these files into a single javascript file jsa-counter.js

To do them, follow the steps below:
– Install fs-extra and concat packages by running command: npm install fs-extra concat.

– Under project folder, create elements-build.js file:

– In package.json, add a build command to NPM scripts:

– Run command: npm run build:elements, we can see that the project tree is updated:

– With jsa-counter.js file, we can use jsa-counter element in any HTML page:

Source Code

– AngularElement
– custom-element-test << just use browser to open index.html for testing.

By grokonez | May 25, 2018.