Getting Started

Let’s start by creating a new Angular Project in our system. For this, make sure that you have the latest version of Angular CLI installed. Run the following command in your terminal:

$ npm install -g @angular/cli

Once this install is complete, we can use it to create a new initial application in our system like this:

$ ng new angular-app

You will then asked to select the additional features that you may want to add to your Angular project, things like routing and the type of stylesheet format. Select the default answer by hitting the Enter/Return key.

The CLI installs the necessary Angular packages and dependencies in a folder called angular-app . You can serve this application on to the browser by running the following commands:

$ cd angular-app

$ ng serve --open

// --open flag will open the browser for you

As you can see, the app contains already contains a few things that we can display on the screen. But we don’t need them. So go back to your code editor (I ❤️ VS Code) and delete everything inside src/app/app.component.html file and write a single <h1> element.

<h1>Welcome To Angular Elements!</h1>

If you take a look at the file structure, you will see that each component in angular consists of a multitude of files. For the App component alone, there is a .ts , .html , .css , and a spec.ts file that contains the tests, and a module.ts file. There will also be an optional routing.module.ts file if you had chosen to add the routing feature to the application while creating it using the CLI.

Instead of writing all these files for our components, Angular CLI gives us a shorthand method that will generate these files for us. Let’s use this method to create a HelloWorld component in our system.

$ ng g c HelloWorld

This single command will create a folder named hello-world inside the app folder. If you open this file, you will find these 4 files inside it:

hello-world.component.css

hello-world.component.html

hello-world.component.spec.ts

hello-world.component.ts

We will only be using the .html and .ts file. There are additional flags that we can pass to the ng g c command. But in order to keep things simple and to point, I won’t use them. Check Angular Docs to know more about how to use this command.

Inside the hello-world.component.ts file, you will see that the selector is set to app-hello-world . So, if you add this to the app.component.html like this:

<h1>Welcome To Angular Elements</h1>

<app-hello-world></app-hello-world>

Then the contents of hello-world.component.html will be displayed in the browser.

Our initial setup is now ready. Let’s get started with how to use Angular Elements.

Convert A Component Into Custom Element

Right now, we have a simple HelloWorld component that simply prints some text on the screen. Let’s take a look at how we can insert this component into the app in a more dynamic fashion. To do this, let’s replace the app-hello-world with a div and a button . Let’s also add the click listener to the button , so that when someone clicks the button, the HelloWorld component can be displayed. This will be handled by a showMessage() function. So go to the app.component.html page and make these changes:

<h1>Welcome To Angular Elements</h1>

<div id="hello"></div>

<button (click)="showMessage()">Display?</button>

We then need to define the showMessage() function in the app.component.ts file. Here we will use regular DOM manipulation to get the div by selecting it using its id of hello . Then, we will apply the innerHTML function to insert the app-hello-world component like this:

export class AppComponent {

showMessage() {

const hello = document.getElementById('hello');

hello.innerHTML = '<app-hello-world></app-hello-world>';

}

}

You can go to your browser and click on the button, but I will tell you right now that nothing is going to happen. But then again, if you go the browser’s dev tools and look there, you will see that the HelloWorld component is inserted.

The reason why we can’t see the component on the screen is that Angular cannot recognize the app-hello-world tag since it has been inserted into the template dynamically. Angular needs all the elements to be present in the template, or you need to use the dynamic component factory to instantiate the component at runtime through your code.

This is where Angular Elements comes into play. By using Angular Element, all we need to do is insert the tag dynamically, and Angular itself will instantiate the component for us. Let’s finally get to see how to use this component in our app. First, use the ng add command to install Angular Elements into our app:

$ ng add @angular/elements

Once you have this installed, go to app.module.ts and make the following changes to the @NgModule :

import {NgModule, Injector} from '@angular/core';

import {createCustomeElement} from '@angular/elements';

@NgModule({

declarations: [AppComponent,HelloWorldComponent],

imports: [BrowserModule,AppRoutingModule],

entryComponents: [HelloWorldComponent],

providers: [],

bootstrap: [AppComponent]

})

Then in the AppModule class, write a constructor function create a new instance of the createCustomElement and pass it the HelloWorldComponent as shown below:

export class AppModule {

constructor(injector: Injector) {

const custom = createCustomElement(HelloWorldComponent, {injector: injector});

}

}

Along with the component, we also have to pass it the injector . The injector is something that we use to resolve the dependencies. With that, we have created an instance of the HelloWorldComponent as a custom element. We can then use the customElements API to define the component’s tag as app-hello-world .

customElements.define('app-hello-world', custom);

Go back to the hello-world.component.ts file and remove/comment the selector inside the @Component section. This way, Angular will not get confused and will know to use the custom element that we just created.

Rerun the ng serve --open command to make sure that Angular takes in all the changes that we have just made.

There is a good chance that the button still does not displays the HelloWorldComponent . This may be because Angular “fails to construct the HTMLElement”. To solve this issue, install the webcomponentjs polyfills:

$ yarn add @webcomponents/webcomponentsjs

Then, go to the polyfills.ts file and import the following:

import '@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js';

Finally! Our custom element will get displayed on the screen when we click that button.