Custom HTML Elements

Hi, everyone! We’re back to Aurelia and this time I’m going to show you how to build your own custom element just with HTML, without a view-model. Yes, that’s possible!

There are many advantages to an HTML-only element, like, first and foremost, not having to use a view-model at all! This is particularly useful when your custom element does not implement complex business logic but you just need a quick component for your applications.

Now, HTML-only custom elements bring us some good and some bad news.

The good news is that you can still add bindable custom attributes to your elements by adding them to the bindable attribute of the template element in a comma separated fashion:

<template bindable="attributeOne, attributeTwo, attributeThree ">


You can then use it like that: 

<require from="./my-element.html"></require> 
<my-element attribute-one="someVar1" attribute-two="someVar2"></my-element> 

Yes, Aurelia does the conversion from camelCase to dash-case on its own all the time. That comes in handy.  
One thing you might have noticed in the example above is that, in order to use an HTML-only element, you also need to include the “.html” extension in your path. That happens mainly due to the absence of a view model. 
The bad news is that HTML-only custom elements do not support two-way binding by default. That means that, if you want two-way binding functionality, you need to explicitly state it. I will demonstrate this with a simple example as it can be very confusing to newcomers: 

The HTML-only element:

And how we can use it:

Working with aurelia-dialog

The Aurelia Dialog is a very useful Aurelia plugin for creating and showing popup dialogs in your Aurelia applications. The official repository can be found here:

aurelia-dialog does not come with the standard Aurelia installation so you need to take some steps before you can use it.

Follow these simple steps to install and start using Aurelia Dialog:


jspm install aurelia-dialog

Go to your Aurelia configuration file (In my demos it’s main.ts) and add the plugin to the Aurelia configuration object as shown below:

The Aurelia Dialog module exports two classes, the DialogController and the DialogService. We can use the first one to create our own custom dialogs and the latter to trigger those dialogs.

In this tutorial, I am going to use the UserInfo class I introduced in my earlier tutorial about sharing state (link here) and display the user’s personal information on a custom dialog that’s triggered when a button is clicked. The dialog will ask the user if the information displayed on it is valid and provide the user with two “Yes” or “No” buttons for answering. The user’s answer will then be logged to the console. It’s a simple example but enough to get you started with creating and managing Aurelia dialogs.

Let’s start by creating a new folder within our src directory named ‘dialog-demo’. We’re going to need to add four files to this folder.
• info-dialog.ts: The view model for our custom ‘Personal Information’ dialog

• info-dialog.html: Where we will design our custom dialog

• dialog-demo.ts: The view-model for the page that will host our shiny new popup dialog

• dialog-demo.html: Will  just contain a button that will trigger the popup


Finally we make the required additions to the configureRouter method of the App class in app.ts to add our new demo page to the router navigation.

{ route: 'dialog-demo', name: 'dialog-demo', moduleId: './dialog-demo/dialog-demo', nav: true, title: 'Dialog Demo' }

Note: At the time of this writing there is still a bug in Aurelia Dialog’s code that prevents the popup dialog from closing when the user clicks outside the box.

You can view the whole repository here for more Aurelia demos