Angular - Angular Elements Component - Create custom HTML tag! (2024)

What are Angular Elements? It is a library which allows us to use components outside of Angular code. In this case, the React frontend team can add features to their application written in Angular.

We use Web Components technology to create the elements. It allows us to create a custom HTML tag which we can repeatedly use in the code. The logic contained in it is not connected with the rest of the code.

Creating an element using Angular API

To begin, let’s create our project, using the Angular CLI.

ng new angular-elements-example

Let’s add angular elements.

ng add @angular/elements

And let’s create a sample component.

ng g c test-component

When the project is finished, we can add our element.

We create the elements using the createCustomElement() method. In order to use it, you need to add it to the main application module.

export class AppModule { constructor(injector: Injector) { const el = createCustomElement(TestComponent, { injector: injector }); customElements.define('test-component', el); }}

In the example above, we used the TestComponent component. Then we defined it as a web element <test-component>.

The component was made dynamic, so we can use it in the code with simple JS code.

Communicating with a component using Input() and Output()

Let’s create a component that will display a User list. We pass the User array through Input() and filter a selection of a particular User through Output().

It’s a good practice to name Input() and Output() with lower case letters. For example, it’s better to label ‘userlist’ instead of ‘userList’. When we add an element to an HTML page we won’t have a problem, but when we add it to a React application it might not work.

Another thing is to treat Input() as a string. When we add elements to other applications, data, like objects or arrays, might be handled incorrectly. Applications will use the toString() function instead of serializing the data. Therefore, a setter is set for userslist that converts JSON or assigns the User array to the property list. The property list is then listed in the view.

import { Component, OnInit, EventEmitter, Input, Output } from '@angular/core';export interface User { name: string;}@Component({ selector: 'app-users-list', templateUrl: './users-list.component.html', styleUrls: ['./users-list.component.sass']})export class UsersListComponent { list: User[]; @Input() set userslist(userslist: User[]|string) { if (typeof userslist === 'string') { try { this.list = JSON.parse(userslist); } catch {} } else if (Array.isArray(userslist)) { this.list = userslist; } } @Output() userselect = new EventEmitter();}<p *ngFor="let user of list" (click)="userselect.emit(user)"> {{ user.name }}</p>

We can add Input() to our element, using the JS code. It’s necessary to refer to the HTML element and then to the userslist attribute.

Elements Build for use in other applications

The application creating the build won’t have an AppComponent or bootstrap with NgModule. They are unnecessary. At this point, we don’t have any components responsible for the root of the application and our application doesn’t need any components to boot.

@NgModule({ imports: [ BrowserModule, FormsModule ], declarations: [ AppComponent, UsersListComponent ],})export class AppModule { constructor(injector: Injector) { const el = createCustomElement(UsersListComponent, { injector: injector }); customElements.define('users-list', el); } ngDoBootstrap() {}}

In the example above, I have added the ngDoBootstrap() function. As no element is defined to start the application, this function tells the application to start.

We are creating a production build without cache mode.

ng build --prod --output-hashing=none

The command in the following folder – dist/angular-elements-example – created 3 files: main.js, polyfills.js, and runtime.js. These need to be merged into one, in order to make uploading to the site easier. Let’s create a demo folder and use the command to merge the 3 files into 1.

cat dist/angular-elements-example/runtime.js dist/angular-elements-example/polyfills.js dist/angular-elements-example/main.js > demo/angular-elements-example.js

We have a complete file – angular-elements-example.js – which we can now add to the website.

I’ve put an example with the build execution on GitHub.

Adding element to HTML page

We can easily import such an element into a simple html page. We have to add the following script – angular-elements-example.js, to the following file – index.html.

At this point, we have 2 implementation options. We can add our element dynamically or statically. In both cases, it is possible to handle Input() and Output().

In the case of static addition, it passes JSON array.

<html> <body> <script src="./angular-elements-example.js"></script> <h1>Static</h1> <users-list userslist='[{"name":"John"},{"name":"IronMan"}]'></users-list> <script> document.querySelector('users-list').addEventListener('userselect', e => alert(`output static ${JSON.stringify(e.detail)}`)); </script> <h1>Dynamic</h1> <script> const el = document.createElement('users-list'); el.userslist = [{name: 'John 2'}, {name: 'IronMan 2'}]; el.addEventListener('userselect', e => alert(`output dynamic ${JSON.stringify(e.detail)}`)); document.querySelector('body').appendChild(el); </script></body></html>

We can see the given example using the HTML page on stackblitz.

Adding an element to a React application

Similar to adding to a simple HTML page, we need to add a JS file with our element. To do so we add it to the src directory in the React project and implement it in the index.js file.

Convert the data passed in Input() into JSON. As I mentioned above React uses the toString() method instead of serializing the data.

The Output() handling of the component is done using addEventListener. In the React component, the EventListener needs to be removed after deleting it.

import React, { Component } from 'react';import './App.css';class App extends Component { users = JSON.stringify([{name: 'John Wick'}, {name: 'IronMan'}]); componentDidMount() { this.component.addEventListener('userselect', this.onUserSelect); } componentWillUnmount() { this.component.removeEventListener('userselect', this.onUserSelect); } onUserSelect(event) { console.log(event.detail); } handleRef = component => { this.component = component; }; render() { return ( <users-list userslist={this.users} ref={this.handleRef}></users-list> ); }}export default App;

We can see the given example using React on stackblitz.

Adding a component to a Vue application

When adding an element to a component in Vue, we will apply the same principles as in the case of React. We will replace the User array with JSON.

In the case of Output() handling, the function will return CustomEvent. In order to get more information, refer to detail.

<template> <users-list :userslist="users" @userselect="userselect"></users-list>;</template><script> export default { name: 'App', data() { return { users: JSON.stringify([{ name: "John Wick" }, { name: "IronMan" }]) } }, methods: { userselect(event) { alert(JSON.stringify(event.detail)) } } }</script>

The given example using Vue can be seen on stackblitz.

Summary

Angular Elements is a great tool if we want to share pieces of Angular code. We can use them in microservices or UI components. I think this technology is worth familiarizing with. What is your experience with Web Components? Do you use them in your projects? Let us know in the comments.