Angular Elements — A Walkthrough

How to implement Angular Elements within Angular — and leverage their capabilities to enhance your development process.

I’ve been eager to explore Angular Elements for some time now. With Angular Elements, developers gain the ability to encapsulate their Angular components as self-contained custom web elements, offering the advantages of portability and autonomy.

In this article, I will provide you with a concise yet comprehensive walkthrough of the steps necessary to implement Angular Elements within an Angular application (v.16). Together, we will explore how to harness the power of Angular Elements and leverage their capabilities to enhance your development process.

Defining the components

To create a standalone web element first we need the elements package.

npm install @angular/elements --save

Once the package is added, create the components as you normally would in an Angular app. You can pass parameters to the component with the Input decorator and also emit with the Output decorator.

A sample component

Once the component is created. Open app.module.ts file and in the @NgModule decorator parameters, remove the bootstrap key.

You can also optionally remove the import to app.component file and remove all references to it ie., from declarations array and delete all files related to app.component.

The next step would be to define our components as web components. In the app module class implement the ngDoBootstrap lifecycle hook and define our component as a web component.

In the above code, we use the createCustomElement method exported by the @angular/elements package to create the custom web element. Then we use the customElements.define web API to define a new custom element, note that customElements is a web API and is not linked to Angular. In the above code the first parameter to customElements.define ie., ‘hello-world’ refers to the tag name of the web component, that is you will use that component as <hello-world></hello-world>

A sample is shown below:

Custom element definition

Note that in the above code, we have defined 2 custom components. It is possible to export multiple components and also we pass the same injector instance to both elements, this allows the components to share the same injector and hence we can share the same instance of services with dependency injection.

Building the components

You can build the app as you normally would:

ng build --output-hashing none

That is it, now you can just copy all the js and CSS files from the dist folder to your web project, and add them to a script tag to use the web components. However, since there are multiple js files in the dist folder, it might be a good idea to bundle them into a single js file and distribute it. To do so add the following packages

npm install fs-extra concat --save-dev

Once the packages are added add a file element-build.js with the following code to the root of your project:

Note, you may have to modify the above script to suit your project, especially the dist folder path and name of the bundle and once you have created the file, add the following script to package.json:

"build:elements": "ng build --output-hashing none && node element-build.js"

Now when you modify the components you can just run:

npm run build:elements

And the component will be bundled into a single js file.

Using the Components

To use the components add the bundle js to the web page and use the newly defined tags as you normally use any HTML tags.

Notice the title attribute, this is the @Input(‘title’) we used while creating the component. Similarly, we can also listen to events emitted from the element:

In this article, we covered a step-by-step guide on implementing Angular web components. While the process is intriguing, it’s worth considering that the final bundle size turned out to be substantial (approximately 139kb for just 2 small components). For smaller applications, an alternative solution like Alpinejs might be more fitting than utilizing Angular elements.

Have you used Angular elements in your projects? If you have any additional suggestions, tips, or experiences to share, I would love to hear from you! Please feel free to leave your feedback. Thank you for taking the time to explore this guide and happy coding!

The demo code can be found in the following repo:

GitHub - pratheeshrussell/angular-elements-demo