This guide will take you through creating a hello world app using Aurelia and briefly explain its main concepts. We will be building a simple hello, world example with a text field you can enter a name into and watch the view update. We assume you are familiar with JavaScript, HTML, and CSS.

When you complete this guide, you'll be ready to take your first steps building your own Aurelia app and, you'll have the resources you need to continue into more advanced topics. So, what are you waiting for? Let's get started!

In our hello world example we touched upon some very basic and light Aurelia concepts. The most important of those is the view/view-model relationship. However, please note that you can write Aurelia applications in a wide variety of different ways, including custom elements without view models.

It is highly recommended that you have a read through additional sections in the "Getting Started" section to become familiar with the templating syntax, building components with bindable properties, looping through collections and more.

Once you are familiar with Aurelia's templating syntax and conventions, you will discover that you end up applying these templating basics to every app that you build.

In your view templates, you can specify inline variables using the <let> custom element.

The <let> element supports working with interpolation strings, plain strings, referencing view model variables, and other let bindings within your templates.

<let some-var="This is a string value"></let>

You could then display this value using its camelCase variant:

<p>${someVar}</p>

You can bind to variable values in a <let> too:

<let math-equation.bind="1 + 2 + 5"></let>

<!-- This will display 8 -->
<p>${mathEquation}</p>

Learn about enabling SVG binding in Aurelia template.

Adding SVG registration

By default, Aurelia won't work with SVG elements, since SVG elements and their attributes require different parsing rules. To teach Aurelia how to handle SVG element bindings, add the SVGAnalyzer like the following example:

import { SVGAnalyzer } from '@aurelia/runtime-html';
import { Aurelia } from 'aurelia';

Aurelia
    .register(SVGAnalyzer) // <-- add this line
    ...

After adding this registration, bindings with attributes will work as expected and the syntax is the same with the other bindings. Readmore on the basic binding syntax of Aurelia .

Welcome to the magical world of Javascript development. This guide is for any newcomer to front-end development who isn't that experienced with modern tooling or Javascript frameworks.

Getting started

For the purposes of this tutorial and as a general rule for any modern framework like Aurelia, you will be using a terminal of some sort. On Windows, this can be the Command Prompt or Powershell. On macOS, it'll be Terminal (or any other Terminal alternative), the same thing with Linux.

Aurelia 2’s templating system offers a powerful and intuitive way to build and manage the user interface of your web application. It goes beyond the traditional boundaries of HTML, infusing it with enhanced capabilities to create dynamic and interactive user experiences. At the heart of Aurelia 2's templating is the seamless connection between your HTML templates and the underlying JavaScript or TypeScript code, enabling a responsive and data-driven UI.

In Aurelia 2, templates are not just static HTML files. They are dynamic views that interact with the underlying logic of your application, responding to user actions and data changes. This integration makes your development process more efficient, allowing you to build complex UIs with less code and greater clarity.

From the moment you scaffold a new Aurelia 2 project, you engage with templates that are both familiar in their HTML structure and powerful in their extended functionality. Whether defining the layout for a new component or displaying data in your HTML, Aurelia 2's templating syntax is designed to be both developer-friendly and highly expressive.

There are various ways that you can set up an Aurelia project, including everything from adding a simple script tag to your HTML page to creating a custom configuration. One of the easiest and most powerful ways to get started is by using

Before you run makes, you will need a recent version of Node.js installed on your machine. If you do not have Node.js, you can Please ensure that Node.js is up-to-date if you already have it installed.

Next, using , a tool distributed with Node.js, we'll create a new Aurelia app. Open a command prompt and run the following command:

makes will then start the Aurelia project wizard, asking you a few questions to help you get things set up properly. When prompted, give your project the name "hello-world" and then select a default setup, either ESNext (Javascript) or TypeScript, depending on your preference. Finally, choose "yes" to install the project dependencies.

Introduction

Aurelia was designed to make building web applications and rich UI's easy. Living by the mantra of; Simple, Powerful and Unobtrusive, you have everything you need right out of the box to start building feature-rich web applications.

This section aims to give you a brief technical overview of how Aurelia works, but it is not intended to be a tutorial or reference. If you are looking for a nice gentle introduction to Aurelia that will only take a few minutes of your time the Hello World tutorial is a great place to start.

Core concepts

The core concepts of Aurelia are simple; HTML, CSS and Javascript. While Aurelia does introduce its own templating language you will need to become familiar with, it is enhanced HTML, so the syntax and concepts will feel familiar to you already.

View models and views

Underpinning Aurelia is the view-model and view convention. Out-of-the-box, Aurelia assumes that your components are made up of both a view model (.js or .ts file) as well as an accompanying view with a .html file extension.

If you have worked with .NET or other frameworks that use similar concepts, the view-model and view paradigm will be familiar with you. The view-model contains the business logic and data, the view is responsible for displaying it.

Like all concepts in Aurelia, these are default conventions and can be changed as needed.

Dependency injection

Much like other fully-featured Javascript frameworks and once again, .NET, Aurelia features a robust dependency injection system that allows you to manage your in-app dependencies. You will learn about the benefits of dependency injection in other parts of the documentation, but it plays a fundamental part in Aurelia.

Install node.js

To create new Aurelia applications using the Aurelia CLI via Makes, you will need to ensure you have Node.js installed. The latest version of Node is always recommended and preferable. While Node can be installed through different methods, the easiest is to obtain a distributable from the .

Create an app

Aurelia does not require you to install any global Node packages, instead of using the scaffolding tool, new Aurelia applications can be generated by running the following command.

You will then be presented with the Aurelia CLI screen which will first ask for a project name, then guide you through some options. The fastest way to get started is by choosing either the ESNext or TypeScript default options (1 and 2).

We highly recommend choosing TypeScript for any new Aurelia applications. With TypeScript you get the benefits of intellisense and type safety.

Run the app

Once the CLI process is finished and you have installed the dependencies for your new app, run npm start in the project directory, a browser window will open up with the new Aurelia application you just generated running.

Ready to dive deeper?

Take a look at our beginner-friendly obligatory hello world introduction to Aurelia . And if you want to dive even deeper (perhaps you've dabbled in Aurelia before) we have a fantastic selection of tutorials .

Aurelia as a default convention works on the premise of a view and view-model, both of which are tied together. The view-model is where your business logic lives and, if you have ever worked with .NET before (or other frameworks), you might refer to this as the controller.

Navigate to the src directory where your application code lives and open up the my-app(.ts/.js file. This is the main entry point for the application and this file is where business logic would live. As you can see, there is not a lot going on at the moment.

export class MyApp {
  message = 'Hello World!';
}

The class property message contains a string and within our view, we are displaying it using interpolation.

<div class="message">${message}</div>

We are now going to create a new component which will be a smarter hello component. Inside of src create a new file called hello-name and use the appropriate file extension depending on whether you are using TypeScript or not. So, hello-name.ts or hello-name.js.

Notice how our new component doesn't look much different than the generated one? That's intentional. We are going to bind to this name property using two-way binding from within our view. We don't need any callback functions to update this value either.

Nice one! You just created a custom element view-model. It might not look like much, but you just learned a very core fundamental concept of building Aurelia applications. A view-model can be as simple and complex as you want it to be.

In the next chapter, we will hook this up with our view and allow a text input to change this value.

Template references in Aurelia 2 provide a powerful and flexible way to connect your HTML templates with your JavaScript or TypeScript view models. Using the ref attribute, you can easily identify and interact with specific parts of your template, making it more efficient to manipulate the DOM or access template data.

Declaring Template References

Basic Usage

Add the ref attribute to an HTML element within your template to create a template reference. This marks the element as a reference, allowing you to access it directly in your view model.

In this example, myInput references the input element, which can be used both in the template and the corresponding view model.

Accessing Reference in Template

Template references are immediately available within the template. For instance, you can display the value of the input field as follows:

This binding displays the current value of the input field dynamically.

Accessing Reference in View Model

To access the referenced element in the view model, declare a property with the same name as the reference. For TypeScript users, it's important to define the type of this property for type safety.

Advanced Usage

Working with Custom Elements and Attributes

Aurelia's ref attribute is not limited to standard HTML elements. It can also be used with custom elements and attributes to reference their component instances (view-models) or controllers.

Custom Element Instance Use component.ref="expression" to create a reference to a custom element's component instance (view-model). This was known as view-model.ref in Aurelia v1.

Custom Attribute Instance Similarly, custom-attribute.ref="expression" can reference a custom attribute's component instance (view-model).

Controller Instance For more advanced scenarios, controller.ref="expression" creates a reference to a custom element's controller instance.

Practical Applications

Template references are incredibly useful for integrating with third-party libraries or when direct DOM manipulation is necessary. Instead of using traditional JavaScript queries to find elements, template references provide a more straightforward, framework-integrated approach.

In the previous section, we created a basic view model, and you are probably sceptical that we are now going to create a view with a text input that updates this value without writing any more Javascript.

Inside the src directory create a new file called hello-name.html this will complicate the view model you already have (hello-name.ts or hello-name.js).

Firstly, let's write the code to display the value. Notice how we are using interpolation to print the value like the default generated my-app.html file was? ${name}

What is Aurelia?

Welcome to Aurelia, the future-oriented, open-source JavaScript platform for crafting extraordinary web, mobile, and desktop applications. At its core, Aurelia is more than just a framework; it believes in the unbridled power of open web standards. With Aurelia, your development experience is streamlined, intuitive, and remarkably flexible.

Aurelia isn't just feature-rich; it's a testament to high performance and extensive extensibility, offering a component-oriented design that's fully testable. It's built for developers who know the value of simplicity and the importance of conventions that don't obstruct but enhance creativity. 😎

Aurelia makes it easy to modify an element inline class list and styles. You can work with not only strings but also objects to manipulate elements.

Binding HTML Classes

The class binding allows you to bind one or more classes to an element and its native class attribute.

If you followed along with our tutorial, you would now have a functional hello world application. The application will function like the one below. Typing into the text input field should dynamically display the value you entered.

In Aurelia 2, templates are designed to limit direct access to global variables like window or document for security reasons. However, there are scenarios where access to certain global variables is necessary. Aurelia allows access to a predefined list of global variables commonly used in development.

To reduce boilerplate, Aurelia allows template expression to access a fixed list of global variables that are usually needed. Those globals are as follows:

Global Examples

The Aurelia binding language provides commands like .bind, .one-way, .trigger, .for, .class etc. These commands are used in the view to express the intent of the binding, or in other words, to build binding instructions.

Although the out-of-box binding language is sufficient for most use cases, Aurelia also provides a way to extend the binding language so that developers can create their own incredible stuff when needed.

In this article, we will build an example to demonstrate how to introduce your own binding commands using the @bindingCommand

The router emits several events via the , allowing you to listen to router events. In some situations, you might opt for a router hook, but in other cases, an event might be what you are after.

A good example of where using events might be more appropriate is showing and hiding loaders and other parts of your applications related to routing.

The events fired are:

• au:router:router-start

Aurelia provides a multitude of different wants to observe properties in your components and call a callback function when they change.

The following sections in the observation documentation will help you decide which observation strategy is appropriate for your applications, from the most commonly used to more advanced observation strategies.

The @observable approach

The easiest way to watch for changes to specific view model properties is using the @observable

The <au-viewport> element is where all of the routing magic happens, the outlet. It supports a few different custom attributes, allowing you to configure how the router renders your components. It also allows you to use multiple viewports to create different layout configurations with your routing.

Named viewports

The router allows you to add multiple viewports to your application and render components into each viewport element by their name. The <au-viewport> element supports a name attribute, which you'll want to use if you have more than one.

Error message

yyyy not registered, did you forget to add @singleton()?

Error message

Attempted to jitRegister an intrinsic type: yyyy. Did you forget to add @inject(Key)

Quick introduction

HTML elements are special objects that often require different observation strategies, and most of the time, listening to some specific event is the preferred way. For this reason, Aurelia encourages using events to observe HTML elements.

As an example, the value property of an <input /> element should be observed by listening to the <input /> change events such as input or change on the element. Another example is the value property of a <select /> element should be observed by listening to the change event on it.

By default, the observation of HTML elements is done using a default node observer locator implementation. This default locator has a basic set of APIs that allows users to teach Aurelia how to observe HTML element observation effectively.

The following is the trimmed interface of the node observer locator, highlighting its capability to learn how to observe HTML elements:

useConfig and useConfigGlobal are two methods that can be used to teach the default node observer locator what events can be used to observe a property of a specific element or any element.

Node observer examples

Using the nodeObserverLocator API, we can tell Aurelia how to observe properties of HTML elements for changes. Under the hood, Aurelia already observes properties like values on form inputs, but it is good to understand how this functionality works, especially for custom elements and web components.

How to teach Aurelia to observe the value property of a <textarea /> element:

In this example, the eventsConfig argument has the value { events: ['input', 'change']}.

How to teach Aurelia to observe property length of an <input /> element:

In this example, eventsConfig argument has the value { events: ['input']}.

How to teach Aurelia observe property scrollTop of all elements:

In this example, eventsConfig argument has the value { events: ['scroll']}.

Observing custom elements in Web Components

It should be the same as observing custom (HTML) elements and normal HTML elements. It is common for Web Components to have well-defined events associated with their custom properties, so observing them often means adding a few configuration lines.

An example of how to teach Aurelia to observe the value property of a <my-input /> element, and <my-input /> dispatches valueChanged event when its value has been changed:

Unlike the @watch decorator, the @observable decorator allows you to decorate properties in a component and optionally call a change callback when the value changes. It works quite similarly to the @bindable property.

By convention, the change handler is a method whose name is composed of the property_name and the literal value 'Changed'. For example, if you decorate the property color with @observable, you have to define a method named colorChanged() to be the change handler.

This is what a basic observable would look like using conventions:

When the color value is changed, the colorChanged callback will be fired. The new changed value will be the first argument, and the existing one will be the second one.

If you prefer, you can also put the @observable decorator on classes:

Specifying a different change callback

If you do not want to use the convention, you can define the callback name for the change handler by setting the callback property of the @observable decorator:

Please see below a reference to each Dependency Injection related error with explanations and resources for debugging and solving.

• AUR0001

• AUR0002

Aurelia 2 enhances the handling of promises within templates. Unlike Aurelia 1, where promises had to be resolved in the view model before passing their values to templates, Aurelia 2 allows direct interaction with promises in templates. This is achieved through the promise.bind template controller, which supports then, pending, and catch states, reducing the need for boilerplate code.

The promise.bind template controller allows you to use then, pending and catch in your view, removing unnecessary boilerplate.

Conditional rendering in Aurelia 2 is a powerful feature that lets you create dynamic interfaces that respond to your application's state. You can conditionally include or exclude parts of your view using boolean expressions. This guide will walk you through the different techniques provided by Aurelia to manage conditional content.

Using if.bind

The if.bind directive allows you to conditionally add or remove elements from the DOM based on the truthiness of the bound expression.

A common scenario in a single-page application is page transitions. When a page loads or unloads, an animation or transition effect might be used to make it feel more interactive and app-like.

By leveraging , we can perform animations and transition effects in code.

At first glance, this might look like a lot of code, but we do the animation inside of the attaching and detaching hooks. Using the Anime.js animation library, we create two animation functions for sliding our views in and out.

We use the created lifecycle callback to access the host element (the outer element of our custom element) which we will animate. Most of the other callbacks determine the direction we are heading in.

There are situations that some elements of a custom element should be rendered at a different location within the document, usually at the bottom of a document body or even inside of another element entirely. Aurelia supports this intuitively with the portal custom attribute.

While the location of the rendered element changes, it retains its current binding context. A great use for the portal attribute is when you want to ensure an element is displayed in the proper stacking order without needing to use CSS hacks like z-index:9999

Using the portal attribute without any configuration options will portal the element to beneath the document body (before the closing body tag).

The Observer Locator API allows you to watch properties in your components for changes without the need for using the @observable decorator. In most cases, manual observation will not be required using this API, but it is there if you want it.

Basic observer interface

By default, an observer locator is used to create observers and subscribe to them for change notification.

Binding behaviors are a category of view resources, just like value converters, custom attributes and custom elements. Binding behaviors are most like value converters in that you use them declaratively in binding expressions to affect the binding.

The primary difference between a binding behavior and a value converter is binding behaviors have full access to the binding instance, throughout its lifecycle. Contrast this with a value converter, which can only intercept values passing from the model to the view and visa versa.

The additional "access" afforded to binding behaviors gives them the ability to change the behaviour of the binding, enabling a lot of interesting scenarios, which you'll see below.

Throttle

Aurelia ships with a handful of behaviors out of the box to enable common scenarios. The first is the throttle binding behavior which limits the rate at which the view-model is updated in two-way bindings or the rate at which the view is updated in to-view binding scenarios.

By default, throttle will only allow updates every 200ms. You can customize the rate, of course. Here are a few examples.

Updating a property, at most, every 200ms

HTML

The first thing you probably noticed in the example above is the & symbol, used to declare binding behavior expressions. Binding behavior expressions use the same syntax pattern as value converter expressions:

• Binding behaviors can accept arguments: firstName & myBehavior:arg1:arg2:arg3

• A binding expression can contain multiple binding behaviors: firstName & behavior1 & behavior2:arg1.

• Binding expressions can also include a combination of value converters and binding behaviors:

Here's another example using throttle, demonstrating the ability to pass arguments to the binding behavior:

Updating a property, at most, every 850ms

The throttle behavior is particularly useful when binding events to methods on your view-model. Here's an example with the mousemove event:

Handling an event, at most, every 200ms

Flush pending throttled calls

Sometimes, it's desirable to forcefully run the throttled update so that the application syncs the latest values. This can happen in a form when a user previously was typing into a throttled form field and hit the tab key to go to the next field, as an example. The throttle binding behavior supports this scenario via signal. These signals can be added via the 2nd parameter, like the following example:

Debounce

The debounce binding behavior is another rate-limiting binding behavior. Debounce prevents the binding from being updated until a specified interval has passed without any changes.

A common use case is a search input that triggers searching automatically. You wouldn't want to make a search API on every change (every keystroke). It's more efficient to wait until the user has paused typing to invoke the search logic.

Update after typing stopped for 200ms

Update after typing stopped for 850ms

Like throttle, the debounce binding behavior shines in event binding.

Here's another example with the mousemove event:

Call mouseMove after the mouse stops moving for 500ms

Flush pending debounced calls

Sometimes, it's desirable to forcefully run the throttled update so that the application syncs the latest values. This can happen in a form when a user previously was typing into a throttled form field and hit the tab key to go to the next field, as an example. Similar to the , The debounce binding behavior supports this scenario via signal. These signals can be added via the 2nd parameter, like the following example:

UpdateTrigger

The update trigger allows you to override the input events that cause the element's value to be written to the view model. The default events are change and input.

Here's how you would tell the binding to only update the model on blur:

Update on blur

Multiple events are supported:

Update with multiple events

Signal

The signal binding behavior enables you to "signal" the binding to refresh. This is especially useful when a binding result is impacted by global changes outside **** the observation path.

For example, if you have a "translate" value converter that converts a key to a localized string- e.g. ${'greeting-key' | translate} and your site allows users to change the current language, how would you refresh the bindings when that happens?

Another example is a value converter that uses the current time to convert a record's datetime to a "time ago" value: posted ${postDateTime | timeAgo}. When this binding expression is evaluated, it will correctly result in posted a minute ago. As time passes, it will eventually become inaccurate. How can we refresh this binding periodically to correctly display 5 minutes ago, then 15 minutes ago, an hour ago, etc?

Here's how you would accomplish this using the signal binding behaviour:

Using a Signal

In the binding expression above, we're using the signal binding behavior to assign the binding a "signal name" of my-signal. Signal names are arbitrary. You can give multiple bindings the same signal name if you want to signal multiple bindings simultaneously.

Here's how we can use the ISignaler to signal the bindings periodically:

Signaling Bindings

oneTime

With the oneTime binding behavior you can specify that string interpolated bindings should happen once. Simply write:

One-time String Interpolation

This is an important feature to expose. One-time bindings are the most efficient type of binding because they don't incur any property observation overhead.

There are also binding behaviors for toView and twoWay which you could use like this:

To-view and two-way binding behaviours

Self

With the self binding behavior, you can specify that the event handler will only respond to the target to which the listener was attached, not its descendants.

For example, in the following markup

Self-binding behavior

onMouseDown is your event handler, and it will be called not only when user mousedown on header element, but also all elements inside it, which in this case are the buttons settings and close. However, this is not always the desired behaviour. Sometimes, you want the component only to react when the user clicks on the header itself, not the buttons. To achieve this, onMouseDown method needs some modification:

Handler without self-binding behavior

This works, but business/ component logic is now mixed up with DOM event handling, which is unnecessary. Using self binding behaviour can help you achieve the same goal without filling up your methods with unnecessary code:

Using self-binding behavior

Using self-binding behavior

Custom binding behaviors

You can build custom binding behaviors just like you can build value converters. Instead of toView and fromView methods, you'll create bind(binding, scope, [...args]) and unbind(binding, scope) methods. In the bind method, you'll add your behavior to the binding, and in the unbind method, you should clean up whatever you did in the bind method to restore the binding instance to its original state.

The binding argument is the binding instance whose behavior you want to change. It's an implementation of the Binding interface. The scope argument is the binding's data context. It provides access to the model the binding will be bound to via its bindingContext and overrideContext properties.

Here's a custom binding behavior that calls a method on your view model each time the binding's updateSource / updateTarget and callSource methods are invoked.

Log Binding Behavior

Logs the current binding context to the console whenever the binding updates. This is useful for understanding the data context of a particular binding at runtime.

Tooltip Binding Behavior

Temporarily adds a tooltip to the element, showing the current value of the binding. This can be a quick way to inspect binding values without console logging.

Highlight Updates Binding Behavior

This binding behavior will highlight an element by changing its background color temporarily whenever the binding's target value changes. This visual cue can help developers quickly identify which UI parts react to data changes.

Introduction

In many instances, when working with templated views in Aurelia, you will be approaching development from a reusability mindset. However, sometimes, you need a template for one specific application part. You could create a component for this, but it might be overkill. This is where local templates can be useful.

<template as-custom-element="person-info">
  <bindable name="person"></bindable>
  <div>
    <label>Name:</label>
    <span>${person.name}</span>

export class App {
  public readonly sleuths: Person[] = [
    new Person('Byomkesh Bakshi', '66, Harrison Road'),
    new Person('Sherlock Holmes'

The example defines a template inside the my-app.html markup that can be used as a custom element. The name of the custom element, so defined, comes from the value of the as-custom-element attribute used on the template.

In this case, it is named as person-info. A custom element defined that way cannot be used outside the template that defines it; in this case, the person-info is, therefore, unavailable outside my-app. Thus, the name 'local template'.

Local templates can also optionally specify bindable properties using the <bindable> tag as shown above. Apart from property, other allowed attributes that can be used in this tag are attribute, and mode. In that respect, the following two declarations are synonymous.

Although it might be quite clear, it is worth reiterating that the value of the bindable attribute should not be camelCased or PascalCased.

Why use local templates

In essence, the local templates are similar to HTML-Only custom elements, with the difference that the local templates cannot be reused outside the defining custom element. Sometimes we need to reuse a template multiple times in a single custom element.

Creating a separate custom element for that is a bit overkill. Also, given that the custom element is only used in one single custom element, it might be optimized for that and not meant to be reused outside this context. The local templates are meant to promote that, whereas having a separate custom element makes it open for reuse in another context.

In short, it aims to reduce boilerplate code and promotes highly cohesive, better-encapsulated custom elements.

This means that the following is a perfectly valid example. Note that the local templates with the same name (foo-bar) are defined in different custom elements.

Features and pitfalls

Like anything, there is always an upside and downside: local templates are no different. While they can be a powerful addition to your Aurelia applications, you need to be aware of the caveats when using them, as you may encounter them.

Local templates are hoisted.

It is theoretically possible to go to an infinite level of nesting. That is, the following example will work. However, whether such composition is helpful depends on the use case.

Although it might provide a stronger cohesion, as the level of nesting grows, it might not be easy to work with. It is up to you to decide on a reasonable tradeoff while using local templates.

In this respect, a good thumb rule is to keep the local function analogy in mind.

Custom elements cannot contain only local templates

The following examples will cause a (jit) compilation error.

A local template always needs to be defined directly under the root element

The following example will cause a (jit) compilation error.

Local templates need to have a name

The following example will cause a (jit) compilation error.

Local template names need to be unique

The following example will cause a (jit) compilation error.

Bindable tags need to be under the local template root

The following example will cause a (jit) compilation error.

The property attribute on bindable tags is mandatory

The following example will cause a (jit) compilation error.

Every component instance has a lifecycle that you can tap into. This makes it easy for you to perform various actions at particular times.

For example, you may want to execute some code as soon as your component properties are bound but before the component is first rendered. Or, you may want to run some code to manipulate the DOM as soon as possible after your element is attached to the document.

Constructor

When the framework instantiates a component, it calls your class's constructor, just like any JavaScript class. This is the best place to put your basic initialization code that is not dependent on bindable properties.

Furthermore, the constructor is where you handle the injection of dependencies using dependency injection. You will learn about DI in the , but here is a basic example of where the constructor is used.

Hydrating

The "hydrating" hook allows you to add contextual DI registrations (to controller.container) to influence which resources are resolved when the template is compiled. It is still considered part of "construction".

Hydrated

The "hydrated" hook is a good place to influence how child components are constructed and rendered contextually. It runs synchronously after the definition is compiled (which happens synchronously after hydrating) and, like hydrating, can still be considered part of "construction".

Created

The "created" hook is the last hook that can be considered part of "construction". It is called (synchronously) after this component is hydrated, which includes resolving, compiling and hydrating child components. In terms of the component hierarchy, the created hooks execute bottom-up, from child to parent (whereas hydrating and hydrated are all top-down). This is also the last hook that runs only once per instance.

Here you can perform any last-minute work that requires having all child components hydrated, which might affect the bind and attach lifecycles.

Binding

If your component has a method named "binding", then the framework will invoke it after the bindable properties of your component are assigned. In terms of the component hierarchy, the binding hooks execute top-down, from parent to child, so your bindables will have their values set by the owning components, but the bindings in your view are not yet set.

You can optionally return a Promise either making the method asynchronous or creating a promise object. If you do so, it will suspend the binding and attaching of the children until the promise is resolved. This is useful for fetching/save of data before rendering.

Bound

If your component has a method named "bound", then the framework will invoke it when the bindings between your component and its view have been set. This is the best place to do anything that requires the values from let, from-view or ref bindings to be set.

Attaching

If your component has a method named "attaching, " the framework will invoke it when it has attached the component's HTML element. You can queue animations and/or initialize certain 3rd party libraries.

Attached

If your component has a method named "attached", the framework will invoke it when it has attached the current component and all of its children. In terms of the component hierarchy, the attached hooks execute bottom-up.

Detaching

If your component has a method named "detaching", then the framework will invoke it when removing your HTML element from the document. In terms of the component hierarchy, the detaching hooks execute bottom-up.

Unbinding

If your component has a method named "unbinding, " the framework will invoke it when it has fully removed your HTML element from the document. In terms of the component hierarchy, the unbinding hooks execute bottom-up.

Dispose

If your component has a method named "dispose", then the framework will invoke it when the component is to be cleared from memory completely. It may be called, for example, when a component is in a repeater, and some items are removed that are not returned to the cache.

Lifecycle Hooks

The lifecycle hooks API supports all of the above lifecycle methods. Using the lifecycleHooks decorator, you can perform actions at various points of the component lifecycle. Because the router uses lifecycle hooks, they are documented in the router section, but do not require the use of the router to use (except for router-specific hooks).

Others

For <au-compose>, there are extra lifecycle hooks that are activate/deactivate. Refers to for more details.

When dealing with Aurelia and custom elements, we tend to use the @bindable decorator to define bindable properties. The bindable properties are members of the underlying view model class. However, there are cases where we want to work directly with attributes of the DOM elements.

For example, we want an <input> element with a maxlength attribute and map a view model property to the attribute. Let us assume that we have the following view model class:

Then, intuitively, we would write the following template:

This binds the value to the maxlength attribute of the <input> element. Consequently, the input.maxLength is also bound to be 10. Note that binding the value of the maxLength attribute also sets the value of the maxLength property of the input element. This happens because Aurelia, in the background, does the mapping for us.

On a broad level, this is what attribute mapping is about. This article provides further information about how it works and how to extend it.

How it works

To facilitate the attribute mapping, Aurelia uses IAttrMapper, which has information about how to map an attribute to a property. While creating property binding instructions from , it is first checked if the attribute is a bindable. If it is a bindable property, the attribute name (in kebab-case) is converted to the camelCase property name. However, the attribute mapper is queried for the target property name when it is not a bindable. If the attribute mapper returns a property name, then the property binding instruction is created with that property name. Otherwise, the standard camelCase conversion is applied.

If we want to bind a non-standard <input> attribute, such as fizz-buzz, we can expect the input.fizzBuzz property to be bound. This looks as follows.

Extending the attribute mapping

The attribute mapping can be extended by registering new mappings with the IAttrMapper. The IAttrMapper provides two methods for this purpose. The .useGlobalMapping method registers mappings applicable for all elements, whereas the .useMapping method registers mapping for individual elements.

To this end, we can grab the IAttrMapper instance while bootstrapping the app and register the mappings (there is no restriction, however, on when or where those mappings are registered). An example might look as follows.

In the example above, we are registering a global mapping for foo-bar attribute to FooBar property, which will apply to all elements. We are also registering mappings for individual elements. Note that the key of the object is the of the element; thus, for an element, it needs to be the element name in upper case. In the example above, we map the fizz-buzz attribute differently for <input> and <my-ce> elements.

With this custom mapping registered, we can expect the following to work.

Use two-way binding for attribute

In addition to registering custom mappings, we can teach the attribute mapper when using two-way binding for an attribute. To this end, we can use the .useTwoWay method of the IAttrMapper. The .useTwoWay method accepts a predicate function determining whether the attribute should be bound in two-way mode. The predicate function receives the attribute name and the element name as parameters. If the predicate function returns true, then the attribute is bound in two-way mode, otherwise it is bound in to-view mode.

An example looks as follows.

In this example, we are instructing the attribute mapper to use two-way binding for fizz-buzz attribute of <my-ce> element. This means that the following will work.

Live example

A similar example can be seen in action below.

This section details how you can use the load method on the router instance or load attribute to navigate to other parts of your application.

Programmatically using the load method

To use the load method, you have first to inject the router into your component. This can be done easily by using the IRouter decorator on your component constructor method. The following code will add a property to your component, which we can reference.

Navigating without options

The load method can accept a simple string value allowing you to navigate to another component without needing to supply configuration options.

You could also use the string value method to pass parameter values and do something like this where our route expects a product ID, and we pass 12:

Specifying load options

The router instance load method allows you to specify different properties on a per-use basis. The most common one is the title property, which allows you to modify the title as you navigate your route.

A list of available load options can be found below:

• title — Sets the title of the component being loaded

• parameters — Specify an object to be serialized to a query string and then set to the query string of the new URL.

• fragment

These option values can be specified as follows and when needed:

HTML load attribute

The router also allows you to decorate links and buttons in your application using a load attribute, which works the same way as the router instance load method.

If you have routes defined on a root level (inside of my-app.ts) you will need to add a forward slash in front of any routes you attempt to load. The following would work in the case of an application using configured routes.

The load attribute can do more than accept a string value. You can also bind to the load attribute for more explicit routing. The following example is a bit redundant as specifying route:product would be the same as specifying load="product" , but if you're wanting more explicit routing, it conveys the intent better.

And where things start to get interesting is when you want to pass parameters to a route. We use the params configuration property to specify parameters.

In the above example, we provide the route (id) value (via route: profile). But, then also provide an object of parameters (via params.bind: { name: 'rob' }).

These parameter values correspond to any parameters configured in your route definition. In our case, our route looks like this:

Redirecting

Depending on the scenario, you will want to redirect users in your application. Unlike using the load API on the router where we manually route (for example, after logging in) redirection allows us to redirect inside router hooks.

Please see the section to learn how to implement redirection inside your components.

You can use the lifecycle hooks (instance and shared) to intercept different stages of the navigation when you are working with the routed components directly. However, if you want to tap into different navigation phases from a non-routed component, such as standalone service or a simple custom element, then you need to leverage router events. This section discusses that.

Emitted events

The router emits the following events.

• au:router:location-change: Emitted when the browser location is changed via the and events.

• au:router:navigation-start: Emitted by router before executing a routing instruction; or in other words, before performing navigation.

• au:router:navigation-end: Emitted when the navigation is completed successfully.

• au:router:navigation-cancel: Emitted when the navigation is cancelled via a non-true return value from canLoad or canUnload lifecycle hooks.

• au:router:navigation-error: Emitted when the navigation is erred.

Subscribing to the events

The events can be subscribed to using the . However, there is another type-safe alternative to that.

To this end, inject the IRouterEvents and use the IRouterEvents#subscribe.

Note that the event-data for every event has a different type. When you are using TypeScript, using IRouterEvents correctly types the event-data to the corresponding event type and naturally provides you with intellisense. This type information won't be available if you subscribe to the events using the event aggregator.

The following example demonstrates the usage of router events, where the root component displays a spinner at the start of navigation, and removes it when the navigation ends.

This is shown in action below.

Application Startup

Aurelia allows you to configure the application startup in a couple of different ways. A quick setup where some defaults are assumed and a verbose setup where you can configure some of the framework-specific behaviors.

Quick startup

The quick startup approach is what most developers will choose.

Verbose Startup

To start an Aurelia application, create a new Aurelia() object with a target host and a root component and call start().

In most instances, you will not use the verbose approach to starting your Aurelia applications. The verbose approach is more aimed at developers integrating Aurelia into existing web applications and views.

Register a globally available custom element

Registering a single element

To make a custom element globally available to your application, pass the custom element constructor to the .register() method on your Aurelia app.

Register a set of elements

If you have a package that exports all your custom elements, you can pass the entire package to the .register() method on your Aurelia app.

src/components/index.ts:

src/main.ts:

An introduction to enhance

Enhancement in Aurelia allows for integrating Aurelia’s capabilities with existing DOM elements or dynamically inserted HTML content. This feature is particularly useful in scenarios where the application is not entirely built with Aurelia, such as when integrating with server-rendered pages or dynamically generated content.

The startup sections showed how to start Aurelia for an empty root node. While that's the most frequent use case, there might be other scenarios where we would like to work with an existing DOM tree with Aurelia.

Basic Syntax and Key Points

The basic usage of enhance is straightforward:

Key Points to Understand:

1. Anonymous Custom Element Hydration: The enhancement treats the target node as an anonymous custom element, allowing Aurelia to apply its behavior to the existing DOM structure.

2. Component Flexibility: The component parameter in enhance can be a custom element class, a class instance, or an object literal. If a class is provided, it's instantiated by Aurelia's dependency injection container, which can be either provided or automatically created.

3. Host Element: The host is typically an existing DOM node that is not yet under Aurelia's control. It's crucial to note that

Example of deactivating an application root:

Enhancing During Application Startup

Enhance can be particularly useful during application startup, especially when integrating Aurelia into an existing web page or alongside other frameworks.

Let's create an index.html file containing some HTML markup you would encounter if you generated an Aurelia application using npx makes aurelia or other means.

Pay attention to the contents of the <body> as there is a container called app as well as some HTML tags <my-app>

Now, let's enhance our application by using the enhanceAPI inside of main.ts

Or if your component has one of its lifecycle return a promise:

We first wrap our async code in an anonymous async function. This allows us to catch errors and throw them to the console if enhancement fails, but take note of the enhance call itself. We supply the host element (in our case, it's a DIV with an ID of app as the host).

Above our enhance call, we register our main component, MyApp, the initial component our application will render.

This approach will work for existing applications as well. Say you have a WordPress website and want to create an Aurelia application on a specific page. You could create a container and pass the element to the host on the enhance call.

Enhancing on the fly within components

While using the enhance during registration, the enhance API is convenient for situations where you want to control how an Aurelia application is enhanced. There are times when you want to enhance HTML programmatically from within components. This may be HTML loaded from the server or elements created on the fly.

In the following example, we query our markup for an item-list element and insert some Aurelia-specific markup into it (a repeater).

As you can see, we are dynamically injecting some HTML into an existing element. Because this is being done after Aurelia has already compiled the view, it would not work. This is why we must call enhance to tell Aurelia to parse our inserted HTML.

You can use this approach to enhance HTML inserted into the page after initial compilation, which is perfect for server-generated code.

Not to be confused with the task queue in Aurelia 1, the TaskQueue in Aurelia is an advanced scheduler designed to handle synchronous and asynchronous tasks efficiently. It provides a robust solution to common issues like timing problems, memory leaks, and race conditions often arising from traditional JavaScript timing functions like setTimeout, setInterval, and unmanaged promises.

Benefits of Using the Task Queue

• Improved Performance: By managing tasks more efficiently, the TaskQueue enhances the performance of applications.

• Synchronous and Asynchronous Support: It supports both synchronous and asynchronous tasks, providing greater flexibility in handling tasks.

• Deterministic Task Execution: Facilitates testing by providing deterministic ways to wait for task completion, reducing test flakiness.

• Avoids Common Pitfalls: Helps avoid common issues associated with setTimeout and setInterval, such as memory leaks and race conditions.

Examples and Use Cases

Replacing setTimeout (Synchronous)

Instead of `setTimeout, ' the TaskQueue offers a more reliable way to queue tasks without delay.

If you were to use a native setTimout, it would look like this:

Advantages Over setTimeout

• *Testability: You can await PLATFORM.taskQueue.yield() or use PLATFORM.taskQueue.flush() in tests for predictable task execution.

• Improved Reliability: Reduces the chances of intermittent and hard-to-debug failures.

setTimeout (asynchronous)

For asynchronous operations, the TaskQueue can handle tasks without the issues of floating promises.

Implementing setInterval

The TaskQueue can mimic setInterval functionality, offering more control and reliability.

Replacing requestAnimationFrame

For tasks that need to synchronize with the browser's repaint, domWriteQueue is a safer alternative to requestAnimationFrame.

Animation Loop with requestAnimationFrame

For continuous animations, the TaskQueue can be used to create a loop, similar to requestAnimationFrame.

Testing is integral to modern software development, ensuring that your code behaves as expected in various scenarios. Aurelia 2 facilitates testing by providing helper methods and utilities to instantiate the framework in a test environment. While Aurelia supports different test runners, such as Jest and Mocha, the core testing principles remain consistent across these tools.

Aurelia's dedicated testing library, @aurelia/testing, offers helpful functions for testing, including fixture creation methods that instantiate components with ease and handle both setup and teardown processes.

In Aurelia, testing often involves integration tests where you interact with the DOM and observe changes to content, rather than pure unit tests, which focus solely on isolated logic. It's important to test the behavior of code within the context of the view, but unit testing individual pieces of logic is also highly recommended for a comprehensive test suite.

Configuring the Test Environment

Setting up a consistent test environment is crucial to ensure tests run correctly in different environments. This setup involves initializing the Aurelia platform using the setPlatform method and configuring the Aurelia application's environment to operate within the test runner.

Initialization Code

Place the following initialization code in a shared file to be loaded by all your tests, or include it in each individual test suite:

Using the Initialization Function

By creating the bootstrapTestEnvironment function, you can easily initialize the test environment at the beginning of each test suite. This approach ensures consistency and reduces code duplication:

With your test environment configured, you can now focus on writing effective tests for your Aurelia components, ensuring that they perform as intended under various conditions.

Lambda expressions in Aurelia templates offer a concise and powerful way to include JavaScript-like functionality directly within your HTML using a subset of Arrow Function syntax. This feature enhances the expressiveness of Aurelia's templating engine, allowing for more inline, readable, and maintainable code.

Array methods with repeat.for

One of the most common scenarios will likely be calling Array methods on an array you're looping over using repeat.for.

The CustomElement resource is a core concept in Aurelia 2, enabling developers to create encapsulated and reusable components. Understanding how to leverage the CustomElement API is crucial for building robust applications. In this documentation, we will delve into the usage of CustomElement and its methods, providing detailed examples and explanations.

CustomElement.for

Routing with Aurelia feels like a natural part of the framework. It can easily be implemented into your applications in a way that feels familiar if you have worked with other frameworks and library routers. Here is a basic example of routing in an Aurelia application using router-lite.

Testing custom attributes in Aurelia is analogous to testing components, with the primary difference being that custom attributes do not have a view template. They are, however, responsible for modifying the behavior or appearance of existing DOM elements. By leveraging the same testing techniques used for components, we can effectively validate the functionality of our custom attributes.

Example Custom Attribute

Let's consider a ColorSquareCustomAttribute that we previously created. This attribute applies a color border and sets the size of an element, resulting in a square of uniform dimensions with a colored background.

Getting started

Aurelia comes with a flexible and powerful logging system that allows you to display debug and error messages in your applications in a slightly better way than using native console.log statements.

Reasons to use logging inside of your apps and plugins include helpful debug messages for other developers (living comments) or displaying helpful information to the end-user in the console when something goes wrong.

Overview

Creating injectable services is crucial for building maintainable applications in Aurelia. Services encapsulate shared functionalities such as business logic or data access, and can be easily injected where needed. This guide will demonstrate various methods for creating injectable services, including the use of DI.createInterface() and directly exporting classes.

Attribute binding in Aurelia is a powerful feature that allows you to bind to any native HTML attribute in your templates. This enables dynamic updates to element attributes such as classes, styles, and other standard HTML attributes.

Basic Binding Syntax

The basic syntax for binding to attributes in Aurelia is straightforward:

You can bind to almost any attribute listed in the comprehensive HTML attributes list, which can be found .

The Event Aggregator is a pub/sub-event package that allows you to publish and subscribe to custom events inside your Aurelia applications. Some parts of the Aurelia framework use the event aggregator to publish certain events at various stages of the lifecycle and actions taking place.

Aurelia's testing library enhances the developer experience by offering a Fluent API for creating test fixtures. This API provides a more readable, flexible, and chainable way to set up component tests. With the Fluent API, you can incrementally build your test fixture, making the configuration of your tests more intuitive and maintainable.

Understanding the Fluent API

The Fluent API for createFixture comprises a series of chainable methods that allow you to configure each aspect of your test fixture in a step-by-step manner. This methodical approach to building test fixtures is particularly beneficial when dealing with complex setups or when you need to express the configuration in a more descriptive way.