1 of 100

The Aurelia 2 Docs

Introduction

Get acquainted with Aurelia, the documentation, and how to get started.

What is Aurelia?

Aurelia is an open-source, JavaScript, front-end platform designed to enable you to easily build even the most demanding web, mobile, or desktop applications. Aurelia stands out for its commitment to open web standards and no-nonsense, get-out-of-your-way conventions that enable vanilla JavaScript development. Of course, Aurelia is also packed full of features, performs at the highest standards, is extensible to its core, and supports a fully testable component-oriented design. But you knew all that already, didn't you? 😎

To get started, jump to our Quick Start Guide, or read on to get more of an overview.

Getting Started

Quick start

Before you can build an application with Aurelia, you need to meet a couple of prerequisites.

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 for new developers

New to Javascript, Node.js and front-end development in general? Don't worry, we got you.

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.

To work with Aurelia, you will need to install Node.js. If you are new to Node.js, it is used by almost every tool in the front-end ecosystem now, from Webpack to other niche bundlers and tools. It underpins the front-end ecosystem.

Hello world

Learn the basics of Aurelia by building an interactive Hello, World! application

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.

Here's what you'll learn...

How to set up a new Aurelia project.
Creating components from view-models and views.
The basics of templating and binding.
Where to go from here.

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!

Creating your first app

Learn to use Aurelia's project scaffold tooling to create your first project setup.

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 Webpack configuration. One of the easiest and most powerful ways to get started is by using the makes tool.

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 get it here. Please ensure that Node.js is up-to-date if you already have it installed.

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

npx makes aurelia

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.

You have now created a hello world app without writing a single line code, well done. However, we'll be updating our app to allow for text input so we can make it say, "Hello" to whoever we want in the next section.

You now have an Aurelia setup ready for you to run, debug, or deploy. To ensure that everything is working properly, cd into your project folder and run npm start. Your project will then build and a web browser will open, displaying the message "Hello World".

Congratulations! 🎊 You just ran your first Aurelia app. Now, let's get building.

Your first component - part 1: the view model

A view-model is where your business logic will live for your components. Follow along as you create your first view-model.

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.

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

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

Your first component - part 2: the view

Use a declarative approach to describe how your component should be rendered.

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} the value inside the curly braces references the class property we defined in the previous section, by the name of name.

I would say run the app and see it in action, but we haven't imported our custom element just yet. Let's do that now.

Inside of my-app.html replace the entire file with the following:

We use the import element to include our newly created component. Take note there is a lack of file extension. This is because Aurelia will know to include our view-model and, in turn, include our view and any styles.

We then reference our custom element by its name. Aurelia knows using default conventions to take the file name, strip the file extension and use that as the tag name (this is configurable but beyond the scope of this tutorial).

If you were to run the app using npm start you would then see your application rendering your new component. You should see the text, Hello, Person! rendering in the view. Once you have the app running, leave it running as any changes you make will automatically be detected and re-rendered.

Binding the name to a text input

We have a functional custom element, but we promised we would be able to update the name with any value we want. Inside of hello-name.html add the following beneath the existing heading.

You should now see a text input with the value Person inside of it. By adding value.bind to the input, Aurelia will use two-way binding by default. This means it will show the value from the view-model inside of the view, and if it changes in either view or view-model, it will be updated. Think of a two-way binding as syncing the value.

Type something into the text input and you should see the heading value change as you type. This works because Aurelia binds to the native value property of the text input and keeps track of the changes for you without needing to use callbacks or anything else.

As you might have noticed, there really is not that much code here. Leveraging Aurelia's conventions and defaults allows you to write Aurelia applications without the verbosity and without writing tens of lines of code to do things like binding or printing values.

Running our app

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.

Next steps

Understand what areas of the framework to learn next, and how to proceed from here on out.

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.

Templates

Advanced Attribute Binding)

How it works

Aurelia, by default, will automatically bind properties to attributes using the native binding syntax. This is accomplished by using a mapping function that converts an aurelia property into a native html attribute. See the attribute mapper for an example of how this is done.

Attributes are turned into camel-case equivalent properties by default if there's no mapping specified, so for example, some-fake-attribute.bind="prop" will set someFakeAttribute on the element properties to the value of prop.

In some cases though, not all properties will be mapped automatically to attributes. In these cases, you have several options.

Attribute tag

One method is to replace .bind with .attr. This will ensure that the property is correctly mapped to the attribute.

Attribute binding behavior

Another option is to apply the attribute (`.attr). This also gives you the ability to specify binding type.

Extend the attribute mapper

TODO: This section is in progress

SVG

A developer guide for enabling SVG binding in the Aurelia.

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:

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 .

Components

Getting to know Aurelia

Portalling elements

An element in two places at once.

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).

Observation

Observe changes in your applications.

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 decorator which provides an easy way to watch for changes to properties and react accordingly.

Observing property changes with @observable

Learn how to work with Aurelia's observable decorator to create reactive properties inside your component view models that have change callbacks.

Unlike the , 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

HTML observation

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

Using observerLocator

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.

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

A basic observer has the following interface:

interface IObserver {
  subscribe(subscriber)
  unsubscribe(subscriber)
}

The subscribe method of an observer can be used to subscribe to the changes that it observes. This method takes a subscriber as its argument.

A basic subscriber has the following interface:

interface ISubscriber {
  handleChange(newValue, oldValue)
}

An observer of an object property can be retrieved using an observer locator.

An example of this is:

And to subscribe to changes emitted by this observer:

What is Dependency Injection?

Learn about why Dependency Injection (DI) is so important and what role it plays in Aurelia.

What is DI, and why would I use it?

As a system increases in complexity, it becomes more and more important to break complex code down into groups of smaller, collaborating functions or objects. However, once we’ve broken down a problem/solution into smaller pieces, we have introduced a new problem: how do we put the pieces together?

One approach is to have the controlling function or object directly instantiate all its dependencies. This is tedious but also introduces the bigger problem of tight coupling and muddies the controller's primary responsibility by forcing upon it a secondary concern of locating and creating all dependencies. Inversion of Control (IoC) can be employed to address these issues.

Simply put, the responsibility for locating and/or instantiating collaborators is removed from the controlling function/object and delegated to a 3rd party (the control is inverted).

Resolvers

Getting started

Internally, the DI Container figures out how to locate each dependency using a Resolver. Which resolver is used depends on if or how the dependency was registered. (See below for ) However, you can specify a special resolver when you declare your dependencies.

For example, perhaps your application has an Inspector composed of Panel instances. You may want to inject the panels into the inspector. However, there isn't just one Panel; multiple different types of panels implement the Panel interface. In this case, you'd want to use the all resolver. Here's what that would look like with a plain class:

And with a decorator...

Routing

Viewports

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.

In this example, we have the main viewport for our main content, and another viewport called

Route Events

The router emits several events via the Event Aggregator, which allows you to listen to router events as they occur. 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 that relate to routing.

The events fired are:

au:router:router-start
au:router:router-stop
au:router:navigation-start
au:router:navigation-end
au:router:navigation-cancel
au:router:navigation-error

To listen to these events, you subscribe to them using the event aggregator like this:

As you might expect, these events are named in an intuitive way depending on the action taking place inside of the router.

You will want to listen to the end, cancel and error navigation events if you're relying on displaying and hiding parts of the UI based on the router, to ensure you're checking for a true "done" state.

Router-lite

Developer Guides

0001 to 0015

Errors 0001 to 0015 are Dependency Injection errors.

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

AUR0001

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

Error message

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

Parameters

Interface name

Error explanation

A DI container is trying to resolve an instance of an interface, but there is no registration for it. This means the instance you are trying to load has not been registered with Dependency Injection.

Possible solutions

Ensure that you are registering your interface with Aurelia. This can be done inside of the register method on the Aurelia instance or through the DI methods themselves.

Please also note that this error could be caused by a plugin and not your application. After ruling out that the error is not being caused by your code, try removing any registered plugins one at a time to see if the error resolves itself.

AUR0002

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

Error message

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

Parameters

Name of the key being resolved

Error explanation

A DI container is trying to resolve a key, but there's not a known strategy for it.

Possible solutions

Try adding a strategy for your resolved key. You can do this using @singleton or other forms of DI resolution

AUR0003

Cyclic dependency found: name

Error message

Cyclic dependency found: name

Invalid resolver returned from the static register method

Error message

Invalid resolver returned from the static register method

Vite

Recipes

Learn how to achieve certain tasks in Aurelia applications. From working with third-party libraries to working with different types of data.

Markdown integration

One of the interesting features of Aurelia 2 is the use of different file types such as Markdown as View along with HTML. To do this, follow the steps below:

Create a skeleton with Webpack as a bundler and add markdown-loader configuration at the end of therules as following:

For this setting to work, you need to install the related package as well.

As a final step, we need to introduce the .md files into the TypeScript so find the resource.d.ts under src folder and append the following code into it.

Securing an app

Introduction

The first rule of securing client-side applications is: the client cannot be trusted. Your backend should never trust the input from the front end under any circumstance. Malicious individuals often know how to use browser debug tools and manually craft HTTP requests to your backend.

You may even find yourself in a situation where a disgruntled employee (or former employee), an engineer with intimate knowledge of the system, is seeking revenge by attempting a malicious attack.

Your primary mechanism for securing any SPA application, Aurelia or otherwise, is to work hard at securing your backend services.

Security Advice

This article only contains a few basic tips. It is in no way exhaustive, nor should it be your only resource for securing your application. The bulk of the security work you will set up in your application falls on your server-side technology. You should spend adequate time reading up on and understanding security best practices for whatever backend tech you have chosen.

Authentication and authorization

When designing your application, consider which backend API calls can be made anonymously, which require a logged-in user, and which roles or permissions are required for various authenticated requests.

Ensure that your entire API surface area is explicitly covered in this way. Your front end can facilitate the login process, but ultimately this is a backend task. Here are a few related recommendations:

Make sure your server is configured to transmit sensitive resources over HTTPS. You may want to transmit all resources this way. It is more server-intensive, but it will be more secure. You must decide what is appropriate for your application.
Don't transmit passwords in plain text.
There are various ways to accomplish CORS. Prefer to use a technique based on server-supported CORS rather than client-side hacks.

You can improve the user experience by plugging into Aurelia's router pipeline with your security specifics. Again, remember, this doesn't secure your app but only provides a smooth user experience. The real security is on the backend.

We have a working example to learn how to implement authorization checks using the router.

Validation and sanitization

The backend should always perform validation and sanitization of data. Do not rely on your client-side validation and sanitization code. Your client-side validation/sanitization code should not be seen as anything more than a User Experience enhancement designed to aid honest users. It will not affect anyone acting maliciously.

Here are a few things you should do, though:

Use client-side validation. This will make your users happy.
Avoid data-binding to innerHTML. If you do, be sure to use a value converter to sanitize the input from the user.
Be extra careful anytime you are dynamically creating and compiling client-side templates based on user input.

We Are Trying To Help You

Internally, Aurelia makes no use of eval or the Function constructor. Additionally, all binding expressions are parsed by our strict parser, which does not make globals like window or document available in binding expressions. We've done this to help prevent some common abuses.

Secret data

Do not embed private keys into your JavaScript code. While the average user may not be able to access them, anyone with ill intent can download your client code, un-minify it and use basic regular expressions on the codebase to find things that look like sensitive data.

Perhaps they've discovered what backend technology you are using or what cloud services your product is based on simply by studying your app's HTTP requests or looking at the page source. Using that information, they may refine their search based on certain patterns well-known to users of those technologies, making it easier to find your private keys.

If you need to acquire any secret data on the client, it should be done with great care. Here is a (non-exhaustive) list of recommendations:

Always use HTTPS to transmit this information.
Restrict which users and roles can acquire this information to an absolute minimum.
Always use time-outs on any secret keys so that, at most, if an attacker gains access, they can't use them for long.
Be careful how you store these values in memory. Do not store these as class property values or on any object linked to the DOM through data-binding or otherwise. Doing so would allow an attacker to access the information through the debug console. If you must store this information, keep it inside a private (non-exported) module-level variable.

Deployment

When deploying your apps, there are a few things you can do to make it more difficult for attackers to figure out how your client works:

Bundle your application and minify it. This is the most basic obfuscation you can do.
Do not deploy the original client-side source files. Only deploy your bundled, minified app.
For additional security or IP protection, you may want to look into products such as .

Prepare for the inevitable

Even with the most skilled, security-proficient development team, your app will never be 100% protected. This is a fundamental assumption that you should have from the beginning. Expect to be attacked and expect someone to succeed at some point in time. What will you do if this happens? How will you respond? Will you be able to track down the culprit? Will you be able to identify the issue and quickly seal up the breach? You need a plan.

Again, most of this comes down to server-side implementation. Here are a few basic ideas:

Configure server-side logging and make sure it will provide you with useful information. Such information can be very helpful in tracking down how an attack was performed. Make sure you have tools to quickly search through your logs.
Make sure that all logins are logged. If you use an auth-token scheme, ensure all requests log this information.
Never log sensitive data.

Component lifecycles

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.

Every lifecycle callback is optional. Implement whatever makes sense for your component, but don't feel obligated to implement any of them if they aren't needed for your scenario. Some of the lifecycle callbacks make sense to implement in pairs (binding/unbinding, attaching/detaching) to clean up any resources you have allocated.

If you register a listener or subscriber in one callback, remember to remove it in the opposite callback. For example, a native event listener registered in attached should be removed in detached

All arguments on these callback lifecycle methods are optional and, in most cases, will not be needed.

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.

Define

The "define" hook is the go-to hook for dynamic contextual composition. It runs just after the constructor and can be treated like a late interceptor for the @customElement decorator / CustomElement.define api: it allows you to change the CustomElementDefinition created by the framework before it is compiled, as well as making certain changes to the controller (for example, wrapping or overriding the scope).

You'll have the compiled definition of the parent (owning) element available and the custom element's hydration context. The returned definition is the cache key for the compiled definition.

To make a change only the first time the hook is invoked for an instance underneath a particular parent definition (affecting all instances of the type underneath that parent definition), mutate and return the existing definition; to make a contextual change (that needs to be re-compiled per instance), clone the definition before mutating and returning it.

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 runs synchronously right after the define hook and is still considered part of "construction".

From a caching perspective, it has a direct 1-1 parity with the define hook: the hydration is cached per a unique definition that is returned from define (or per parent definition, if no new definition is returned from define).

Therefore, if you need true per-instance contextual registrations (which should be rare), make sure to bust the cache per instance by returning a clone from the define hook.

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" and has a direct 1-1 parity with the define hook from a caching perspective.

This is the last opportunity to add DI registrations specifically for child components in this container or any other way, affecting what is rendered and how it is rendered.

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 define, 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.

This is a good place to perform any work or change anything your view would depend on because data still flows down synchronously. This is the best time to do anything that might affect children. We prefer using this hook over bound, unless you specifically need bound for a situation when binding is too early.

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.

If you return a Promise from this method, it will not suspend the binding/attaching of child components, but it will be awaited before the attached hook is invoked.

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.

This is the best time to invoke code that requires measuring of elements or integrating a 3rd party JavaScript library that requires the whole component subtree to be mounted to the DOM.

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.

If you return a Promise (for example, from an outgoing animation), it will be awaited before the element is detached. It will run in parallel with promises returned from the detaching hooks of siblings/parents.

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.

This is an advanced hook mostly useful for cleaning up resources and references that might cause memory leaks if never explicitly dereferenced.

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.

Routing Lifecycle

The routing lifecycle allows you to run code at different points of the routing lifecycle such as fetching data or changing the UI.

Inside your routable components which implement the IRouteableComponent interface, certain methods are called at different points of the routing lifecycle. These lifecycle hooks allow you to run code inside of your components, such as fetching data or changing the UI itself.

Router lifecycle hook methods are all completely optional. You only have to implement the methods you require. The router will only call a method if it has been specified inside of your routable component. All lifecycle hook methods also support returning a promise and can be asynchronous.

If you are working with components you are rendering, implementing IRouteableComponent will ensure that your code editor provides you with intellisense to make working with these lifecycle hooks easier.

canLoad

The canLoad method is called upon attempting to load the component. If your route has any parameters supplied, they will be provided to the canLoad method as an object with one or more parameters as the first argument.

If you were loading data from an API based on values provided in the URL, you would most likely do that inside canLoad if the view is dependent on the data successfully loading.

The canLoad method allows you to determine if the component should be loaded or not. If your component relies on data being present from the API or other requirements being fulfilled before being allowed to render, this is the method you would use.

When working with the canLoad method, you can use promises to delay loading the view until a promise and/or promises have been resolved. The component would be loaded if we were to return true from this method.

Required data

If you wanted to load data from an API, you could make the canLoad method async, which would make it a promise-based method. You would be awaiting an actual API call of some kind in place of ....load data

Unlike other async methods, if the promise does not resolve, the component will not load. The canLoad lifecycle method tells the router if the component is allowed to load. It's a great router method for components that rely on data loading such as product detail or user profile pages.

Redirecting

Not only can we allow or disallow the component to be loaded, but we can also redirect it. If you want to redirect to the root route, return a string with an / inside it. You can return a route ID, route path match or navigation instruction from inside this callback to redirect.

Returning a boolean false, string or RoutingInstruction from within the canLoad function will cancel the router navigation.

loading

The loading method is called when your component is navigated to. If your route has any parameters supplied, they will be provided to the load method as an object with one or more parameters as the first argument.

If you are loading data from an API based on values provided in the URL and the rendering of this view is not dependent on the data being successfully returned, you can do that inside of load.

In many ways, the loading method is the same as canLoad with the exception that loading cannot prevent the component from loading. Where canLoad can be used to redirect users away from the component, the loading method cannot.

All of the above code examples for canLoad can be used with loading and will work the same, with exception of being able to return true or false boolean values to prevent the component being loaded (as we just mentioned).

canUnload

The canUnload method is called when a user attempts to leave a routed view. The first argument of this callback is a INavigatorInstruction it provides information about the next route. You can return a component, boolean or string value from this method.

Like the canLoad method, this is just the inverse. It determines if we can navigate away from the current component.

unloading

The unloading method is called if the user is allowed to leave and is in the process of leaving. The first argument of this callback is a INavigatorInstruction it provides information about the next route.

Like the loading method, this is just the inverse. It is called when the component is unloaded (provided canUnload wasn't false).

Loading data inside of components

A common router scenario is you want to route to a specific component, say a component that displays product information based on the ID in the URL. You request the API to get the information and display it.

Two asynchronous lifecycles are perfect for dealing with loading data: canLoad and load - both supporting returning a promise (or async/await).

If the component you are loading absolutely requires the data to exist on the server and be returned, the canLoad lifecycle method is the best place to do it. Using our example of a product page, if you couldn't load product information, the page would be useful, right?

From the inside canLoad you can redirect the user elsewhere or return false to throw an error.

Similarly, if you still want the view to load, even if we can't get the data, you would use the loadinglifecycle callback.

When you use load and async the component will wait for the data to load before rendering.

Getting information about the currently active route

If you worked with routing in Aurelia 1, you might be accustomed to a currentInstruction property available on the router. In Aurelia 2, this property does not exist. There are, however, two properties on the router called activeNavigation and activeComponents which can be used to achieve a similar result. You can also reference the instruction itself from within route lifecycle functions.

The activeNavigation property contains quite a few properties but most notably has the current URL path, query parameters and other navigation-specific values. You might want to get information about the current route.

Get current route details

We can get information about the current route by accessing the activeComponents array and determining the active component. Still, it is possible that more than one component will be in this array. An easier way is to get the route instruction on the canLoad and loading lifecycle methods.

It might seem like a mouthful, but to get the current instruction that resulted in the viewport's current content, this is the current approach to take from within those aforementioned methods inside your components.

Get query parameters from the URL

The parameters object contains a Javascript object of any URL parameters. If your URL contains /?myprop=22&frag=0 then this object would contain {myprop: '22', frag: '0'} , allowing you to get fragment values.

Setting the title from within components

While you would often set the title of a route in your route configuration object using the title property, sometimes you want the ability to specify the title property from within the routed component itself.

You can achieve this from within the canLoad and load methods in your component. By setting the next.title property, you can override or transform the title.

Conditional Rendering

There are two ways to show and hide content in Aurelia. Conditional rendering allows you to use boolean logic to show and hide things inside Aurelia applications.

Aurelia supports two different ways of conditionally showing and hiding content.

if.bind

You can add or remove an element by specifying an if.bind on an element and passing in a true or false value.

When if.bind is passed false Aurelia will remove the element and all of its children from view. When an element is removed, if it is a custom element or has any associated events, it will be cleaned up, thus freeing up memory and other resources they were using.

In the following example, we pass a value called isLoading , which is populated whenever something is loading from the server. We will use it to show a loading message in our view.

When isLoading is a truthy value, the element will be displayed and added to the DOM. When isLoading is falsy, the element will be removed from the DOM, disposing of any events or child components.

else

There is also a else binding that allows you to create if/else statements too. The if/else functionality works how you might expect. Like Javascript, it allows you to say, "If this, otherwise that."

The else value must be used on an element directly proceeding if.bind , or it will not work.

A note on caching behavior: By default, the if.bind feature will cache the view model/view of the element you are using if.bind . Not being aware of this default behavior can lead to confusing situations where the previous state is retained, especially on custom elements.

Using verbose syntax, you can opt out of caching if this becomes a problem.

When using the verbose syntax, value.bind is the boolean condition that triggers your if.bind condition and cache: false is what disables the cache. Only disable the cache if it becomes a problem.

Be careful. Using if.bind takes your markup out of the flow of the page. This causes both reflow and repaint events in the browser, which can be intensive for large applications with a lot of HTML markup.

show.bind

You can conditionally show or hide an element by specifying a show.bind and passing in a true or false value.

When show.bind is passed false , the element will be hidden, but unlike if.bind it will not be removed from the DOM. Any resources, events or bindings will remain. It's the equivalent of display: none; CSS, the element is hidden but not removed.

In the following example, we are passing a value called isLoading , which is populated whenever something is loading from the server. We will use it to show a loading message in our view.

When isLoading is a truthy value, the element will be visible. When isLoading is falsy, the element will be hidden but remain in view.

switch.bind

To deal with conditional rendering Aurelia also provides the switch template controller. It behaves like if/else in terms of that it does detach the elements from DOM, when the condition does not satisfy. The difference being is that it brings the intrinsic flexibility and semantics of using a switch statement with it.

A typical use-case of switch involves dealing with enums. For example, let's consider the following Status enum.

When tasked with displaying a specific text for a specific member (status) of the Status enum, with only if bind at our disposal, we may end up with the following markup.

Also if there are new statuses added to the Status enum in future, this markup will end up more verbose, and possibly difficult to understand. Moreover, the semantics of the code might as well be somewhat lost. With the usage of the switch/case template controller, the above markup can be written as following.

This behaves in similar fashion a switch in JavaScript behaves. That is it renders the first match, and ignores the rest. For example if the status has a value Status.processing, it will render <span>Processing your order.</span>. Note that it intrinsically avoids matching the following cases after the first match and consequently binding and rendering those elements. That is the basic and typical use-case of the switch/case template controllers. Now let's see some other features of this as well.

default-case

The switch also supports default-case; i.e. this "case" will be matched, if nothing else is matched.

With this markup, if the status is set to Status.unknown or Status.delivered, <span>Unknown.</span> will be rendered.

multi-case

It is possible to map a single element to multiple cases, by binding an array to the case.

For either of Status.received or Status.processing, it will render <span>Order received.</span>. A JavaScript equivalent of this would be the following.

When an array is bound to the case, the value of the switch is matched against the items in the array and not with the array reference.

fall-through

It is also possible to have the switch-case fallthrough in the markup, where you don't want to break after a case has been executed. This means something like this.

Aurelia equivalent of this will be the following.

Assuming that status is set to Status.received, it will end up the rendering the first two <span>s.

By default for every case fallThrough is set to false. If needed, you need to set it to true explicitly. This the reason why we don't need to write the following: <span case="value.bind:'processing'; fall-through.bind: false">Processing your order.</span>.

Miscellaneous examples

This section includes few more interesting examples that you might encounter in real life, and the statutory warnings.

Another usage of switch that we often see in the wild, is to use a static expression for switch and more dynamic expression for case. Therefore, the following is a valid usage of switch.

The switch can be used to provide conditional projection to au-slot. The following markup is rendered as '<foo-bar> <span>Order received.</span> </foo-bar>' with status set to Status.received.

The case can be used with <au-slot> element as well. The following markup is rendered as '<foo-bar> <div> <span>Projection</span> </div> </foo-bar>' with status set to Status.received.

switchs can be nested. For example, the following markup is rendered as <span> Expected to be delivered in 2 days. </span> with status set to Status.delivered.

switch can work without any case attribute in it. However, the case cannot be used with the switch applied to its parent. This applies to the default-case as well.

In fact, it is worth noting that case should be the direct child of switch. For most of the cases Aurelia will throw error otherwise; for other cases, it might lead to unexpected results. If you think, any of the following should be supported, then let us know your use-case.

Creating Routes

Learn all there is to know about creating routes in Aurelia.

The router takes your routing instructions and matches the URL to determine what components to render. When the URL patch matches the configured route path, the component is loaded in the case of configured routes.

To register routes, you can either use the @route decorator or the static routes property static routes to register one or more routes in your application.

Route syntax

The routing syntax used in the Aurelia router is similar to that of other routers you might have worked with before. The syntax will be very familiar if you have worked with Express.js routing.

A route is an object containing a few required properties that tell the router what component to render, what URL it should match and other route-specific configuration options.

At a minimum, a route must contain path and component properties, or path and redirectTo properties. The component and redirectTo properties can be used in place of one another, allowing you to create routes that point to other routes.

The anatomy of a route path

The path property on a route is where you'll spend the most time configuring your routes. The path tells the router what to match in the URL, what parameters there are and if they're required.

A path can be made up of either a static string with no additional values or an array of strings. An empty path value is interpreted as the default route, and only one should be specified.

Parameters are supplied to canLoad and loading router lifecycle callbacks as the first argument. They are passed as an object with key/value pairs. Please consult the section to learn how to access them.

Required named parameters

Named required parameters that are prefixed with a colon. :productId when used in a path, a named required parameter might look like this:

This named parameter is denoted by the colon prefix and is called productId which we will be able to access within our routed component.

Optional named parameters

Named optional parameters. Like required parameters, they are prefixed with a colon but end with a question mark.

In the above example, we have an optional parameter called variation. We know it's optional because of the question mark at the end. This means it would still be valid if you visited this route with supplying the variation parameter.

Using optional name parameters is convenient for routes where different things can happen depending on the presence of those optional parameters.

Wildcard parameters

Wildcard parameters. Unlike required and optional parameters, wildcard parameters are not prefixed with a colon, instead using an asterisk. The asterisk works as a catch-all, capturing everything provided after it.

In the above code example, we can have an endless path after which it is supplied as a value to the canLoad and load methods.

Route configuration options

Besides the basics of path and component a route can have additional configuration options.

id — The unique ID for this route
redirectTo — Allows you to specify whether this route redirects to another route. If the redirectTo path starts with / it is considered absolute, otherwise relative to the parent path.

Redirect

By specifying the redirectTo property on our route, we can create route aliases. These allow us to redirect to other routes. We redirect our default route to the products page in the following example.

Specify routes

When creating routes, it is important to note that the component property can do more than accept inline import statements. You can also import the component and specify the component class as the component property if you prefer.

If you are working with the Aurelia application generated using npx makes aurelia you would already have a my-app.ts file to place your routes in. It's the main component of the scaffolded Aurelia application.

As you will learn towards the end of this section, inline import statements allow you to implement lazy-loaded routes (which might be needed as your application grows in size).

Create routes using a static property

If you have a lot of routes, the static property might be preferable from a cleanliness perspective.

If you have more than a few routes, it might be best practice to write them in a separate file and then import them inside your application.

Defining routes using the route decorator

The syntax for routes stays the same using the decorator. Just how they have defined changes slightly.

Child routes

As your application grows, child routes can become a valuable way to organize your routes and keep things manageable. Instead of defining all your routes top-level, you can create routes inside your child components to keep them contained.

An example of where child routes might be useful in creating a dashboard area for authenticated users.

We add a route in our top-level my-app.ts component where we added routes in our previous examples. Now, we will create the dashboard-page component.

You will notice we create routes the same way we learned further above. However, we are defining these inside a component we use for our dashboard section. Notice how we use the au-viewport element inside of the dashboard-page component.

Lastly, let's create our default dashboard component for the landing page.

Now, we can contain all dashboard-specific routes inside of our dashboard-page component for dashboard views. Furthermore, it allows us to implement route guards to prevent unauthorized users from visiting the dashboard.

Catch all / 404 not found route

When a user attempts to visit a route that does not exist, we want to catch this route attempt using a catch-all route. We can use a wildcard * to create a route that does this.

When using a catch-all wildcard route, ensure that it is the last route in your routes array, so it does not hijack any other valid route first.

A good use of a catch-all route might be to redirect users away to a landing page. For example, if you had an online store, you might redirect users to a products page.

You can also specify a component that gets loaded like a normal route:

Lazy loaded routes

Most modern bundlers like Webpack support lazy bundling and loading of Javascript code. The Aurelia router allows you to create routes that are lazily loaded only when they are evaluated. What this allows us to do is keep the initial page load bundle size down, only loading code when it is needed.

By specifying an arrow function that returns an inline import we are telling the bundler that our route is to be lazily loaded when requested.

Inline import statements are a relatively new feature. Inside your tsconfig.json file, ensure your module property is set to esnext to support inline import statements using this syntax.

Passing information between routes

We went over creating routes with support for parameters in the creating routes section, but there is an additional property you can specify on a route called data, , which allows you to associate metadata with a route.

This data property will be available in the routable component and can be a great place to store data associated with a route, such as roles and auth permissions. In some instances, the route parameters can be used to pass data, but for other use cases, you should use the data property.

Styling Active Router Links

A common scenario is styling an active router link with styling to signify that the link is active, such as making the text bold. When a route is active, by default, a CSS class name of active will be added to the route element.

In your HTML, if you were to create some links with load attributes and visit one of those routes, the active class would be applied to the link for styling. In the following example, visiting the about route would put class="active" onto our a element.

Router configuration

Learn about configuring the Router-Lite.

The router allows you to configure how it interprets and handles routing in your Aurelia applications. The customize method on the RouterConfiguration object can be used to configure router settings.

Choose between hash and pushState routing using `useUrlFragmentHash`

If you do not provide any configuration value, the default is pushState routing. If you prefer hash-based routing to be used, you can enable this like so:

By calling the customize method, you can supply a configuration object containing the property useUrlFragmentHash and supplying a boolean value. If you supply true this will enable hash mode. The default is false.

If you are working with pushState routing, you will need a <base> element with href attribute (for more information, refer ) in the head of your document. The scaffolded application from the CLI includes this in the index.html file, but if you're starting from scratch or building within an existing application you need to be aware of this.

PushState requires server-side support. This configuration is different depending on your server setup. For example, if you are using Webpack DevServer, you'll want to set the devServer.historyApiFallback option to true. If you are using ASP.NET Core, you'll want to call routes.MapSpaFallbackRoute in your startup code. See your preferred server technology's documentation for more information on how to allow 404s to be handled on the client with push state.

Configuring `basePath`

Configuring a base path is useful in many real-life scenarios. One such example is when you are hosting multiple smaller application under a single hosting service. In this case, you probably want the URLs to look like https://example.com/app1/view42 or https://example.com/app2/view21. In such cases, it is useful to specify a different value for every app.

Run the following example to understand how the value defined in base#href is affecting the URLs.

When you open the example in a new browser tab, you can note that the URL in the address bar looks the HOSTING_PREFIX/app/home or HOSTING_PREFIX/app/about. This is also true for the href values in the a tags. This happens because <base href="/app"> is used in the index.ejs (producing the index.html). In this case, the router-lite is picking up the baseURI information and performing the routing accordingly.

This needs bit more work when you are supporting multi-tenancy for your app. In this case, you might want the URLs look like https://example.com/tenant-foo/app1/view42 or https://example.com/tenant-bar/app2/view21. You cannot set the document.baseURI every time you start the app for a different tenant, as that value is static and readonly, read from the base#href value.

With router-lite you can support this by setting the basePath value differently for each tenant, while customizing the router configuration, at bootstrapping phase. Following is an example that implements the aforementioned URL convention. To better understand, open the the example in a new tab and check the URL in address bar when you switch tenants as well as the links in the a tags.

The actual configuration takes place in the main.ts while customizing the router configuration in the following lines of code.

There are also the following links, included in the my-app.html, to simulate tenant switch/selection.

Note the a tags with . Note that when you switch to a tenant, the links in the a tags also now includes the tenant name; for example when we switch to tenant 'foo' the 'Home' link is changed to /foo/app/home from /app/home.

Customizing title

A buildTitle function can be used to customize the . For this example, we assume that we have the configured the routes as follows:

With this route configuration in place, when we navigate to /home, the default-built title will be Home | Aurelia. We can use the following buildTitle function that will cause the title to be Aurelia - Home when users navigate to / or /home route.

Check out the following live example. You might need to open the demo in a new tab to observe the title changes.

Translating the title

When localizing your app, you would also like to translate the title. Note that the router does not facilitate the translation by itself. However, there are enough hooks that can be leveraged to translate the title. To this end, we would use the in the route configuration to store the i18n key.

As data is an object of type Record<string, unknown>, you are free to chose the property names inside the data object. Here we are using the i18n property to store the i18n key for individual routes.

In the next step we make use of the buildTitle customization as well as a AppTask hook to subscribe to the locale change event.

This customization in conjunction with the previously shown routing configuration will cause the title to be Aurelia - Startseite when user is navigated to / or /home route and the current locale is de. Here we are assuming that the i18n resource for the de locale contains the following.

The following example demonstrate the title translation.

Enable or disable the usage of the `href` custom attribute using `useHref`

By default, the router will allow you to use both href as well as load for specifying routes. Where this can get you into trouble is external links, mailto: links and other types of links that do not route. A simple example looks like this:

This seemingly innocent and common scenario by default will trigger the router and will cause an error.

You have two options when it comes to working with external links. You can specify the link as external using the .

Or, you can set useHref to false (default is true) and only ever use the load attribute for routes.

Configure browser history strategy

Using the historyStrategy configuration option it can be instructed, how the router-lite should interact with the browser history object. This configuration option can take the following values: push, replace, and none.

`push`

This is the default strategy. In this mode, the router-lite will interact with Browser history to push a new navigation state each time a new navigation is performed. This enables the end users to use the back and forward buttons of the browser to navigate back and forth in an application using the router-lite.

Check out the following example to see this in action.

The main configuration can be found in the main.ts.

To demonstrate the push behavior, there is a small piece of code in the my-app.ts that listens to router events to create informative text (the history property in the class) from the browser history object that is used in the view to display the information.

As you click the Home and About links in the example, you can see that the new states are being pushed to the history, and thereby increasing the length of the history.

`replace`

This can be used to replace the current state in the history. Check out the following example to see this in action. Note that the following example is identical with the previous example, with the difference of using the replace-value as the history strategy.

As you interact with this example, you can see that new states are replacing old states, and therefore, unlike the previous example, you don't observe any change in the length of the history.

`none`

Use this if you don't want the router-lite to interact with the history at all. Check out the following example to see this in action. Note that the following example is identical with the previous example, with the difference of using the none-value as the history strategy.

As you interact with this example, you can see that there is absolutely no change in the history information, indicating non-interaction with the history object.

Override configured history strategy

You can use the to override the configured history strategy for individual routing instructions.

Configure active class

Using the activeClass option you can add a class name to the router configuration. This class name is used by the when the associated instruction is active. The default value for this option is null, which also means that the load custom attribute won't add any class proactively. Note that the router-lite does not define any CSS class out-of-the-box. If you want to use this feature, make sure that you defines the class as well in your stylesheet.

Router hooks

How to implement router "guards" into your applications to protect routes from direct access.

Router hooks are pieces of code that can be invoked at the different stages of routing lifecycle. In that sense, these hooks are similar to the lifecycle hooks of the routed view models. The difference is that these hooks are shared among multiple routed view models. Therefore, even though the hook signatures are similar to that of the lifecycle hooks, these hooks are supplied with an additional argument that is the view model instance.

If you worked with Aurelia 1, you might know these by their previous name: router pipelines.

Anatomy of a lifecycle hook

Shared lifecycle hook logic can be defined by implementing one of the router lifecycle hooks (canLoad, loading etc.) on a class with the @lifecycleHooks() decorator. This hook will be invoked for each component where this class is available as a dependency.

While the router hooks are indeed independent of the components you are routing to, the functions are basically the same as you would use inside of an ordinary component.

This is the contract for ordinary route lifecycle hooks for components:

And the following is the contract for shared lifecycle hooks.

The only difference is the addition of the first viewModel parameter. This comes in handy when you need the component instance since the this keyword won't give you access to the component instance like it would in ordinary instance hooks.

Example: Authentication and Authorization

Before starting with the involved details of the shared/global lifecycle hooks, let us first create an example lifecycle hook. To this end, we consider the typical use-case of authorization; that is restricting certain routes to users with certain permission claims.

The example we are going to build in this section is just a toy example. For your production code, perform due diligence to evaluate the potential security threats.

For this example, we will create two lifecycle hooks; one for authentication and another is for authorization. However, before directly dive into that, let us briefly visit, how the routes are configured.

Note that the of the route configuration option is used here to define the routes' permission claim. This is used by the auth hooks later to determine whether to allow or disallow the navigation. With that we are now ready to discuss the hooks.

The first hook will check if the current route is protected by a claim and there is a currently logged in user. When there is no logged in user, it performs a redirect to login page. This is shown below.

The second hook will check if the current user has the permission claims to access the route. Where the user does not satisfies the claims requirements the user is redirected to a forbidden page. This is shown below.

Lastly, we need to register these two hooks to the DI container to bring those into action.

Note that the authentication hook is registered before the authorization hook. This ensures that the authentication hook is invoked before than the authorization hook which is also semantically sensible.

To know more about the order of invocation, please refer the respective .

And that's the crux of it. You can see this example in action below.

Note that even though in the example we limit the the hooks to only canLoad method, more than one lifecycle methods/hooks can also be leveraged in a shared lifecycle hook (a class decorated by the @lifecycleHooks() decorator).

Global registration vs local dependencies

The lifecycle hooks can be registered either globally (as it is done in the or as .

The globally registered lifecycle hooks are invoked for every components. Thus, it is recommended to use those sparsely. On the other hand, when a hook is registered as a dependency of a particular component, it is invoked only for that one component.

This is shown in the example below, where there are two globally registered hooks, which are invoked for every components.

Note that the globally registered hooks in the example above do nothing significant other than logging the invocations. This is shown below.

The log entries are then enumerated on the view. The following is one such example of log entries.

You may get a different log depending on your test run. However, it can still be clearly observed that both hook1 and hook2 are invoked for every components. Depending on your use-case, that might not be optimal.

To achieve a granular control on the lifecycle hooks, you can register the hooks as the for individual routed view models. This ensures that the lifecycle hooks are invoked only for the components where those are registered as dependencies. This shown in the example below where there are three hooks, and one component has two hooks registered as dependencies and another component has only hook registered.

When ChildOne or ChildTwo is loaded or unloaded you can observe that only Hook2 is invoked for ChildTwo, whereas both Hook1 and Hook2 are invoked for ChildOne. Below is an example log from one of such test runs.

You can see the example in action below.

You can of course choose to use both kind of registrations. The following example shows that Hook3 is registered globally and therefore is invoked for every components whereas Hook1 is only invoked for ChildOne and Hook2 is only invoked for ChildTwo.

Preemption

When using multiple lifecycle hooks, if any hook returns a non-true value (either a false or a navigation instruction) from canLoad or canUnload, it preempts invocation of the other hooks in the routing pipeline.

This is shown in the following example. The example shows that there are two hooks, namely hook1 and hook2. hook1 return false if the path c1 is navigated with a non-number and non-even number; for example it denies navigation to c1/43 but allows c1/42.

You can see the example in action below.

If you run the example and try clicking the links, you can observe that once hook1 returns false, hook2 is not invoked. One such example log is shown below.

Order of invocations

The thumb rule is that the hooks are invoked in the order they are registered. That is if some Hook1 is registered before Hook2 in DI then Hook1 will be invoked before the Hook2. You can see this in the example of .

That is also true, when registering hooks as one of the dependencies for a custom element. You can see this in the example of .

When using both globally registered hooks as well as local dependencies, the global hooks are invoked before the locally registered hooks. You can see this in action in .

Lastly, the shared lifecycle hooks are invoked before the instance lifecycle hooks.

Form Inputs

Handling forms and user input is quite a common task in applications. Whether you are building a login form, data entry, or even a chat application, Aurelia allows you to work with forms intuitively.

In Aurelia, the binding system uses two-way binding as a default for form elements. Text inputs, text areas and even contenteditable elements all use a two-way binding.

Many of the concepts discussed here assume knowledge of how Aurelia's template and binding syntax work. We recommend reading the Template syntax & features section before continuing with this section if you are new to Aurelia.

Data flow in forms

In Aurelia, form elements are reactive, and their changes are directly tied to the underlying view model. Updates flow from the view to the view model, and updates from the view model flow to the view (hence, two-way).

To illustrate how two-way binding works in forms, let's break down the workflow:

The user types a value into the input element. The element is for a first name, so they enter John.
The native form input events are fired, and Aurelia also sees the value has changed.
The binding system sees the new value and notifies the view model to update the value.
Any reference to the bound value will be updated without needing any callback functions or additional notification steps (the value changes).

Creating a basic form

Creating forms in Aurelia requires no special configuration or treatment. Create a form element and add form input controls with bindings. Here is a basic form example for a login form to show you how little code you need.

Firstly, let's create the markup for our login form:

Before we write the view model code, let's break down what we did here:

We created a form with two text inputs
We used value.bind to bind the native value attribute of these fields to the corresponding view model properties
We are calling a function handleLogin when the submit event on the form is triggered to handle the bindable properties inside

Now, the corresponding view model code:

There is not a whole lot of code here for what is happening. Whenever the email or password values change, they will be reflected inside of our view model. Inside the handleLogin method, we would probably validate the data and call an API.

Using submit.trigger on a form will prevent its default action by applying a event.preventDefault behind-the-scenes. This means your form will not submit to the action or method attributes on the form, you will need to handle this manually.

Binding with text and textarea inputs

Binding to text inputs uses a syntax similar to binding to other elements in Aurelia. By default, input elements will use two-way binding, which means the value will update in the view when changed inside the view model and updated in the view model when changed in the view.

Text Input

You can even bind to other attributes on form elements such as the placeholder attribute.

Textarea

A textarea element is just like any other form element. It allows you to bind to its value and, by default, value.bind will be two-way binding (meaning changes flow from out of the view into the view model and changes in the view-model flow back to the view).

Binding with checkbox inputs

Aurelia supports the two-way binding of various data types to checkbox input elements.

Booleans

Bind a boolean property to an input element's checked attribute using checked.bind="myBooleanProperty".

Array of Numbers

A set of checkbox elements is a multiple-selection interface. If you have an array that serves as the "selected items" list, you can bind the array to each input's checked attribute. The binding system will track the input's checked status, adding the input's value to the array when the input is checked and removing the input's value from the array when the input is unchecked.

To define the input's "value", bind the input's model attribute: model.bind="product.id".

Array of Objects

Numbers aren't the only type of value you can store in a "selected items" array. The binding system supports all types, including objects. Here's an example that adds and removes "product" objects from a selectedProducts array using the checkbox data-binding.

Array of Objects with Matcher

You may run into situations where the object your input element's model is bound to do not have reference equality to any objects in your checked array. The objects might match by id, but they may not be the same object instance. To support this scenario, you can override Aurelia's default "matcher", which is an equality comparison function that looks like this: (a, b) => a === b.

You can substitute your chosen function with the right logic to compare your objects.

Array of Strings

Finally, here's an example that adds and removes strings from an selectedProducts array using the checkbox data-binding. This is example is unique because it does not use model.bind to assign each checkbox's value. Instead, the input's standard value attribute is used.

Normally we cannot use the standard value attribute in conjunction with checked binding because it coerces anything assigned to a string. This example uses an array of strings, so everything works just fine.

Binding with radio inputs

A radio input group is a "single select" interface. Aurelia supports two-way binding any type of property to a group of radio inputs. The examples below illustrate binding number, object, string and boolean properties to sets of radio inputs. In each of the examples, there's a common set of steps:

Group the radios via the name property. Radio buttons with the same value for the name attribute are in the same "radio button group"; only one radio button in a group can be selected at a time.
Define each radio's value using the model property.
Two-way bind each radio's checked attribute to a "selected item" property on the view model.

Numbers

Let's start with an example that uses a numeric "selected item" property. Each radio input will be assigned a number value via the model property in this example. Selecting a radio will cause its model value to be assigned to the selectedProductId property.

Objects

The binding system supports binding all types of radios, including objects. Here's an example that binds a group of radios to a selectedProduct object property.

Objects with Matcher

You may run into situations where the object your input element's model is bound to does not have reference equality to any of the objects in your checked attribute bound to. The objects might match by id, but they may not be the same object instance. To support this scenario, you can override Aurelia's default "matcher", which is an equality comparison function that looks like this: (a, b) => a === b.

You can substitute your chosen function with the right logic to compare your objects.

Booleans

In this example, each radio input is assigned one of three literal values: null, true and false. Selecting one of the radios will assign its value to the likesCake property.

Strings

Finally, here's an example using strings. This is example is unique because it does not use model.bind to assign each radio's value. Instead, the input's standard value attribute is used. Normally we cannot use the standard value attribute in conjunction with checked binding because it coerces anything assigned to a string.

Binding with select elements

A <select> element can serve as a single-select or multiple-select "picker", depending on whether the multiple attribute is present. The binding system supports both use cases. The samples below demonstrate a variety of scenarios.

All use a common series of steps to configure the selected element:

Add a <select> element to the template and decide whether the multiple attribute should be applied.
Bind the select element's value attribute to a property. In "multiple" mode, the property should be an array. In singular mode, it can be any type.
Define the select element's <option>

Select Number

Select Object

Select Object with Matcher

You may run into situations where the object to your select element's value is bound and does not have reference equality with any of the objects your option element model properties are bound to. The select's value object might "match" one of the option objects by id, but they may not be the same object instance.

To support this scenario, you can override Aurelia's default "matcher", which is an equality comparison function that looks like this: (a, b) => a === b. You can substitute your chosen function with the right logic to compare your objects.

Select Boolean

Select String

Multiple Select Numbers

Multiple Select Objects

Multiple Select Strings

Form Submission

Most of the time, a <form> element should be used to group one or many controls in a form. It acts as a container for those controls and can also be used for layout purposes with CSS.

Normally, HTML forms can be submitted without involving any JavaScript via the action and method attributes on a <form>. Though it's also common in applications that forms are driven by JavaScript.

In Aurelia, driving form via script can be achieved via submit event on the form, with the basic usage looking like the following example:

Note that by default, for a <form/> without a method attribute, or method attribute value being equal to GET/get, using submit.trigger will call preventDefault() on the submit event, which prevents the normally unwanted behavior of html of navigating the page to the URI of the form. If this behavior is not desired, return true in the method being called, like the following example:

Form validation

Validation is an important part of creating good forms. Aurelia provides a robust validation plugin that allows you to validate forms, create custom validation rules and configure every facet of validation in your Aurelia applications.

To learn about form validation using the Aurelia Validation package, please consult the validation documentation below for details.

Configuring routes

Learn about configuring routes in Router-Lite.

The router takes your routing instructions and matches the URL to one of the configured Routes to determine which components to render. To register routes you can either use the @route decorator or you can use the static routes property to register one or more routes in your application. This section describes the route configuration options in details.

Route configuration basics

The routing configuration syntax for router-lite is similar to that of other routers you might have worked with before. If you have worked with Express.js routing, then the syntax will be very familiar to you.

A route is an object containing a few required properties that tell the router what component to render, what URL it should match on and other route-specific configuration options.

The most usual case of defining a route configuration is by specifying the path and the component properties. The idea is to use the path property to define a pattern, which when seen in the URL path, the view model defined using the component property is activated by the router-lite. Simply put, a routing configuration is a mapping between one or more path patterns to components. Below is the simple example (from the section) of this.

For the example above, when the router-lite sees either the path / or /home, it loads the Home component and if it sees the /about path it loads the About component.

Note that you can map multiple paths to a single component. Although these paths can be thought of as aliases, multiple paths, in combination with gets interesting. Another way of creating aliases is to use the configuration option.

Note that the example above uses the @route decorator. In case you cannot use the decorator, you can use the static properties instead. The example shown above can be rewritten as follows.

As the re-written example shows, you can convert the properties in the options object used for the @route decorator into static properties in the view model class.

Apart from the static API including the @route decorator, there is also an instance-level hook named getRouteConfig that you can use to configure your routes. This is shown in the example below.

See this in action below.

Note that the hook is also supplied with a parent route configuration, and the new route node. These values can be nullable; for example, for root node there is no parent route configuration.

The getRouteConfig can also be async. This is shown in the example below.

See this in action below.

`path` and parameters

The path defines one or more patterns, which are used by the router-lite to evaluate whether or not an URL matches a route or not. A path can be either a static string (empty string is also allowed, and is considered as the default route) without any additional dynamic parts in it, or it can contain parameters. The paths defined on every routing hierarchy (note that routing configurations can be hierarchical) must be unique.

Required parameters

Required parameters are prefixed with a colon. The following example shows how to use a required parameter in the path.

When a given URL matches one such route, the parameter value is made available in the canLoad, and load .

Note that the value of the id parameter as defined in the route configuration (:id) is available via the params.id. Check out the live example to see this in action.

Optional parameters

Optional parameters start with a colon and end with a question mark. The following example shows how to use an optional parameter in the path.

In the example, shown above, the Product component is loaded when the router-lite sees paths like /product or /product/some-id, that is irrespective of a value for the id parameter. You can see the live example below.

Note that there is an additional link added to the products.html to fetch a random product.

As the id parameter is optional, even without a value for the id parameter, clicking the link loads the Product component. Depending on whether or not there is a value present for the id parameter, the Product component generates a random id and loads that.

Wildcard parameters

The wildcard parameters, start with an asterisk instead of a colon, act as a catch-all, capturing everything provided after it. The following example shows how to use a wildcard parameter in the path.

In the example, shown above, the Product component is loaded when the router-lite sees paths like /product/some-id or /product/some-id/foo/bar. You can see the live example below.

The example utilizes a wildcard parameter named rest, and when the value of rest is 'image', an image for the product is shown. To this end, the canLoad hook of the Product view-model reads the rest parameter.

Setting the title

You can configure the title for the routes while you are configuring the routes. The title can be configured in the root level, as well as in the individual route level. This can be seen in the following example using the @route decorator.

If you prefer using the static routes property, the title can be set using a static title property in the class. The following example has exactly the same effect as of the previous example.

With this configuration in place, the default-built title will be Home | Aurelia when user is navigated to / or /home route. That is, the titles of the child routes precedes the base title. You can customize this default behavior by using a when customizing the router configuration.

Note that, instead of a string, a function can also be used for title to lazily set the title.

Redirect to another path

By specifying the redirectTo property on our route, we can create route aliases. These allow us to redirect to other routes. In the following example, we redirect our default route to the home page and the about-us to about page.

You can see this action below.

Note that redirection also works when there are multiple paths/aliases defined for the same component.

You can see this action below.

You can use route parameters for redirectTo. The following example shows that the parameters from the about-us path is rearranged to the about path.

You can see this action below.

Fallback: redirecting the unknown path

We can instruct the router-lite to redirect the users to a different configured path, whenever it sees any unknown/un-configured paths. To this end, we can use the fallback configuration option. Following example shows how to use this configuration option.

As the example shows, the fallback is configured as follows.

There is a custom element, named NotFound, which is meant to be loaded when any unknown/un-configured route is encountered. As you can see in the above example, clicking the "Foo" link that is with un-configured href, leads to the NotFound view.

It is recommended that you configure a fallback at the root to handle the navigation to un-configured routes gracefully.

Another way of defining the fallback is to use the . The following example demonstrates this behavior, where the NotFound view can be reached via multiple aliases, and instead of choosing one of these aliases the route-id is used to refer the route.

The name of the custom element, meant to be displayed for any un-configured route can also be used to define fallback. The following example demonstrates this behavior, where not-found, the name of custom element NotFound, is used to refer the route.

An important point to note here is that when you are using the custom element name as fallback, you need to ensure that the custom element is registered to the DI container. Note that in the example above, the NotFound component is registered to the DI container in main.ts.

A fallback defined on parent is inherited by the children (to know more about hierarchical routing configuration, refer the ). However, every child can override the fallback as needed. The following example demonstrate this. The root has two and two children components can be loaded into each of those by clicking the link. Every child defines their own child routing configuration. The root defines a fallback and one of the children overrides the fallback by defining one of its' own. With this configuration in place, when navigation to a un-configured route ('Foo') is attempted for each children, one loads the overridden version whereas the other loads the fallback inherited from the parent (in this case the root).

A function can be used for fallback. The function takes the following signature.

An example can look like below, where the example redirects the user to NF1 component if an attempt to load a path /foo is made. Every other attempt to load an unknown path is results loading the NF2 component.

You can also see this in action below.

You can also use non-string fallbacks. For example, you can use a class as the value for fallback; such as fallback: NotFound. Or, if you are using a function, you choose to return a class instead of returning a string. These combinations are also supported by router-lite.

Case sensitive routes

Routes can be marked as case-sensitive in the configuration, allowing the navigation to the component only when the case matches exactly the configured path. See the example below where the navigation to the "about" page is only successful when the casing matches.

Thus, only an attempt to the /AbOuT path loads the About component; any attempt with a different casing is navigated to the fallback. See this in action below.

Advanced route configuration options

There are few other routing configuration which aren't discussed above. Our assumption is that these options are more involved and might not be used that often. Moreover, to understand the utility of these options fully, knowledge of other parts of the route would be beneficial. Therefore, this section only briefly introduces these options providing links to the sections with detailed examples.

id — The unique ID for this route. The router-lite implicitly generates a id for a given route, if an explicit value for this property is missing. Although this is not really an advanced property, due to the fact that a route can be uniquely identified with id, it can be used in many interesting ways. For example, this can be used to generate the hrefs in the view when using the or using the . Using this property is also very convenient when there are multiple aliases for a single route, and we need a unique way to refer to this route.
transitionPlan — How to behave when the currently active component is scheduled to be loaded again in the same viewport. For more details, please refer the

Specifying component

Before finishing the section on the route configuration, we need to discuss one last topic for completeness, and that is how many different ways you can configure the component. Throughout various examples so far we have seen that components are configured by importing and using those in the routing configuration. However, there are many other ways in which the components can be configured. This section discusses those.

Using inline `import()`

Components can be configured using the or dynamic import. Instead of statically importing the components, those can be imported using import()-syntax, as the example shows below.

You can see this in action below.

If you are using TypeScript, ensure that the module property set to esnext in your tsconfig.json to support inline import statements.

Using the name

Components can be configured using only the custom-element name of the component.

However, when configuring the route this way, you need to register the components to the DI.

You can see this configuration in action below.

Using a function returning the class

Components can be configured using a function that returns a class.

You can see this configuration in action below.

Using custom element definition

Components can be configured using custom element definition.

You can see this configuration in action below.

Using custom element instance

Components can be configured using custom element instance.

You can see this configuration in action below.

Using classes as routes

Using router-lite it is also possible to use the routed view model classes directly as routes configuration. While doing so, if no paths have been explicitly configured for the components, the custom element name and aliases can be used as routing instructions. The following example demonstrates that the C1 and C2 classes are used directly as the child routes for the Root.

The example above implies that router.load('c-1'), or router.load('c-a') and router.load('c-2'), router.load('c-two') will load the C1 and C2 respectively.

To know more about the router API refer .

Distributed routing configurations

The examples discussed so far demonstrate the classic use-cases of route configurations where the parents define the child routes. Another aspect of these examples are that all the route configurations are centralized on the parent component. This section provides some examples where that configuration is distributed across different components.

We start by noting that every component can define its own path. This is shown in the following example.

The example shows that both Home and About uses the @route decorator to define their own paths. This reduces the child-route configuration for MyApp to @route({ routes: [Home, About] }). The example can be seen in action below.

Note that other properties of route configuration can also be used in this way.

The previous example demonstrates that the Home and About components define the title for themselves. The example can be seen in action below.

While adapting to distributes routing configuration, the parent can still override the configuration for its children. This makes sense, because even if a component defines its own path, title etc. the parent may choose to reach (route) the component via a different path or display a different title when the component is loaded. This is shown below, where the MyApp overrides the routing configurations defined by About.

This can be seen in action below.

You can also use the @route decorator and the getRouteConfig together.

This can be seen in action below.

The advantage of this kind of distributed configuration is that the routing configuration of every component is defined by every component itself, thereby encouraging encapsulation, leaving the routing configuration at the parent level to merely listing out its child components. On the other hand, highly distributed route configuration may prevent easy overview of the configured routes. That's the trade-off. Feel free to mix and match as per your need and aesthetics.