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 Node.js website.

Create an app

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

npx makes aurelia

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 here. And if you want to dive even deeper (perhaps you've dabbled in Aurelia before) we have a fantastic selection of tutorials here.

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

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

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

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

<div>
    <h4>Hello, ${name}!</h4>
</div>

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:

<import from="./hello-name"></import>

<hello-name></hello-name>

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.

<div>
    <h4>Hello, ${name}!</h4>
    
    <p><input type="text" value.bind="name"></p>
</div>

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.

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

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

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

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

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

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

export class HelloName {
  name = 'Person';
}

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

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

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

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

Basic Binding Syntax

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

<div attribute-name.bind="value"></div>

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

Binding Techniques and Syntax

Aurelia provides multiple methods for attribute binding, each with its syntax and use cases.

Interpolation Binding

Interpolation allows for embedding dynamic values within strings. Here's an example using interpolation to bind the id attribute:

<div>
    <h1 id="${headingId}">My Heading</h1>
</div>

Keyword Binding

Aurelia supports several binding keywords, each defining the data flow between the view model and the view:

• one-time: Updates the view from the view model once and does not reflect subsequent changes.

• to-view / one-way: Continuously updates the view from the view model.

• from-view: Updates the view model based on changes in the view.

• two-way: Creates a two-way data flow, keeping the view and view model in sync.

• bind: Automatically determines the appropriate binding mode, defaulting to two-way for form elements and to-view for most other elements.

Examples of Keyword Binding

<input type="text" value.bind="firstName">
<input type="text" value.two-way="lastName">
<input type="text" value.from-view="middleName">

<a class="external-link" href.bind="profile.blogUrl">Blog</a>
<a class="external-link" href.to-view="profile.twitterUrl">Twitter</a>
<a class="external-link" href.one-time="profile.linkedInUrl">LinkedIn</a>

Binding to Images

Binding image attributes, such as src and alt, is as simple as:

<img src.bind="imageSrc" alt.bind="altValue">

Disabling Elements

Bind to the disabled attribute to disable buttons and inputs dynamically:

<button disabled.bind="disableButton">Disabled Button</button>

InnerHtml and TextContent

Choose between innerhtml for rendering HTML content and textcontent for text-only content:

<div innerhtml.bind="htmlContent"></div>
<div textcontent.bind="textContent"></div>

Advanced Binding Techniques

How Attribute Binding Works

Aurelia uses a mapping function to convert properties to HTML attributes. The attribute mapper handles the conversion, typically changing kebab-case to camelCase. However, not all properties map directly to attributes.

Using the .attr Tag

If automatic mapping fails, use .attr to ensure proper attribute binding:

<input pattern.attr="patternProp">

Attribute Binding Behavior

Apply the attribute binding behavior with .bind and & attr to specify the binding type:

<input pattern.bind="patternProp & attr">

Event binding in Aurelia 2 provides a seamless way to handle DOM events within your application. By attaching event listeners directly in your view templates, you can easily respond to user interactions such as clicks, key presses, and more. This guide will delve into the specifics of event binding in Aurelia 2, offering detailed explanations and examples to enhance your understanding and usage of this feature.

Understanding Event Binding

Aurelia 2 simplifies the process of binding events to methods in your view model. It uses a straightforward syntax that allows you to specify the type of event and the corresponding method to invoke when that event occurs.

Event Binding Syntax

The general syntax for event binding in Aurelia 2 is as follows:

<element event.trigger="methodName(argument1, argument2, ...)">

• element represents the HTML element to which you want to attach the event listener.

• event is the event you want to listen for (e.g., click, keypress).

• .trigger is the binding command that tells Aurelia to listen for the specified event and call the method when the event is fired.

• methodName is the method's name in your view-model that will be called when the event occurs.

• argument1, argument2, ... are optional arguments you can pass to the method.

Event Binding Commands

Aurelia 2 offers two primary commands for event binding:

1. .trigger: This command attaches an event listener that responds to events during the bubbling phase. It is the most commonly used event-binding command and is suitable for most use cases.

2. .capture: This command listens for events during the capturing phase. It is generally reserved for special circumstances, such as when you need to intercept events before they reach a target element that may prevent their propagation.

Example: Click Event Binding

To listen for a click event on a button and call a method named handleClick, you would write:

<button click.trigger="handleClick()">Click me!</button>

When the button is clicked, your view-model's handleClick method will be executed.

Passing Event Data

You can pass the event object itself or other custom data to your event handler method. For instance, to pass the event object to the handleClick method, you would modify the binding like this:

<button click.trigger="handleClick($event)">Click me!</button>

In your view model, the handleClick method would accept the event object as a parameter:

export class MyViewModel {
  handleClick(event) {
    // Handle the click event
  }
}

Common Events

Aurelia 2 allows you to bind to any standard DOM event. Here are some common events you might use:

Click

The click event is frequently used for buttons, links, and other clickable elements.

<a href="#" click.trigger="navigate()">Go somewhere</a>

Keypress

The keypress event is useful for responding to user input in text fields or when handling keyboard navigation.

<input type="text" keypress.trigger="validateInput($event)" />

Mouseover

The mouseover event can trigger interactions when the user hovers over an element.

<div mouseover.trigger="showTooltip()">Hover over me!</div>

Handling Event Propagation

Sometimes, you may want to stop an event from bubbling up the DOM tree or prevent the default action associated with that event. You can do this within your event handler methods using the event object's methods:

• event.stopPropagation(): Prevents further propagation of the event in the bubbling or capturing phase.

• event.preventDefault(): Cancels the event if it is cancelable without stopping further propagation.

Advanced Event Binding

While the .trigger and .capture commands cover most use cases, Aurelia 2 also allows for more advanced scenarios, such as throttling event handlers for performance reasons or handling custom events.

Throttling Events

To improve performance, especially for events that can fire rapidly like mousemove or scroll, you can throttle the event handler invocation using Aurelia's binding behaviors.

<div mousemove.trigger="handleMouseMove() & throttle:100">Move your mouse over me</div>

In the above example, the handleMouseMove method will be called at most once every 100 milliseconds, no matter how often the mousemove event is fired.

Custom Events

Aurelia 2 supports custom events, which can be useful when integrating with third-party libraries or creating your own custom components.

<custom-element my-event.trigger="handleCustomEvent($event)"></custom-element>

In this example, my-event is a custom event emitted by custom-element, and handleCustomEvent is the method that will respond to it.

Event Binding: Examples and Scenarios

To help you better understand event binding in Aurelia 2, we've compiled a collection of examples and scenarios demonstrating different techniques and best practices. These should give you the insights to handle events in your applications effectively.

Event Binding with Modifiers

Self Binding Behavior

To ensure that an event only triggers a method if the event originated from the element itself (and not from its children), you can use the self binding behavior.

<div click.trigger="divClicked() & self">
  <button click.trigger="buttonClicked()">Button</button>
</div>

This setup guarantees that clicking the button will not trigger the divClicked() method, as the self binding behaviour filters out events bubbling from child elements.

Combining Two-Way Binding with Events

Checkbox Change Event

A checkbox's change in state can be combined with the change event to perform actions in response to user interaction.

<input type="checkbox" checked.bind="agree" change.trigger="onAgreementChange()" />

export class MyViewModel {
  agree = false;

  onAgreementChange() {
    // Logic to handle checkbox state change
  }
}

Keyboard Interaction

Handling Specific Key Presses

To react to specific key presses, such as "Enter" or "Escape", you can inspect the event object within your method.

<input type="text" keydown.trigger="handleKeydown($event)" />

export class MyViewModel {
  handleKeydown(event) {
    switch (event.key) {
      case 'Enter':
        // Handle Enter key press
        break;
      case 'Escape':
        // Handle Escape key press
        break;
      // Add more cases as needed
    }
  }
}

Working with Dynamic Content

Event Delegation for Lists

Event delegation is useful for handling events on dynamically generated content, such as a list of items.

<ul click.trigger="listClicked($event)">
  <li repeat.for="item of items" data-id="${item.id}">${item.name}</li>
</ul>

export class MyViewModel {
  items = []; // Your dynamic array of items

  listClicked(event) {
    const itemId = event.target.getAttribute('data-id');
    if (itemId) {
      // Logic to handle the click event on an item
    }
  }
}

Custom Events and Arguments

Emitting and Responding to Custom Events

Custom elements can publish custom events with associated data, which parent components can listen for and handle.

Custom element:

export class CustomElement {
  // inject host element to dispatch custom event
  host = resolve(Element);
  someMethod() {
    const data = { /* Payload data */ };
    this.host.dispatchEvent(new CustomEvent({ detail: data }))
  }
}

Parent component:

<custom-element my-custom-event.trigger="handleCustomEvent($event)"></custom-element>

Parent view-model:

export class ParentViewModel {
  handleCustomEvent(event) {
    const data = event.detail;
    // Logic to handle the custom event and its data
  }
}

Autocomplete and Search Inputs

Throttling Input for Autocomplete Features

For features like search or autocomplete, where user input can trigger frequent updates, throttling can prevent excessive processing.

<input type="text" input.trigger="search($event.target.value) & debounce:300">

export class MyViewModel {
  search(query) {
    // Logic to perform search based on query
  }
}

Here, the search function is called only after the user has stopped typing for 300 milliseconds, improving performance and user experience.

These examples showcase the versatility of event binding in Aurelia 2. By understanding and applying these patterns, you can create interactive and efficient applications that respond to user actions in a controlled and performant manner.

Event modifiers

When you need to ensure some conditions are met before processing an event, you can use event modifiers. Event modifiers can be specified via event syntax, follow by a colon and modifiers:

[event].trigger[:modifier]="[expression]"

By default, Aurelia handles 2 set of common events: mouse and keyboard events. An example is as follow:

<button click.trigger:ctrl="onCtrlClick()">Next page</button>

In the example above, the handler onCtrlClick() will only be called when the button is clicked while the Ctrl key being pressed. Keyboard event sometimes employ even more complex condition, as per the following example:

<textarea keydown.trigger:ctrl+enter="send()">

In this example, we will only call send() when the user hits the Enter + Ctrl key combo. This example also demonstrates how to use multiple modifiers, they can be separated by the character + as delimiter.

Prevent default and stop propagation

preventDefault and stopPropagation are two functions commonly called on any events. Event modifiers can be used to declaratively and easily call those functions, as per following example:

<button click.trigger:stop:prevent="validate()">Validate</button>

Mouse button modifiers

When handling mouse event, it sometimes requires a specific mouse button. By default, Aurelia provides 3 modifiers left, middle and right to support mouse button verification. An example is as follow:

<button click.trigger:middle="newTab()">Open in new tab</button>

Keyboard mapping

When using keyboard event modifier, sometimes a certain key is used as modifier. You can use the char code representing the key as the modifier, like the following example, where we want to handle the combo Ctrl + K (notice its the upper K):

<textarea keydown.trigger:ctrl+75="openSearchDialog()">

75 is the charcode of the upper case letter K.

Even though direct, it's not always clear 75 means when looking at the template, so it's often desirable to use the real letter K instead. Though Aurelia is not taught to, by default, understand the letter K means the code 75. You can teach Aurelia by adding to the IKeyMapping:

import { AppTask, IKeyMapping } from 'aurelia';

Aurelia.register(
  AppTask.creating(IKeyMapping, mapping => {
    mapping.keys.upper_k = 'K';
  })
)

After this enhancement, the :ctrl+upper_k modifier will be understood as ctrl+75 or ctrl + upper K key.

Note that we cannot use the upper case letter K as modifier in HTML because HTML is case insensitive. We use, in this example, upper_k as an alternative for that, and add the mapping accordingly.

Conclusion

Event binding in Aurelia 2 is a powerful and intuitive feature that enables you to create dynamic and responsive applications. By understanding the syntax and capabilities of event binding, you can harness the full potential of Aurelia 2 to handle user interactions gracefully and effectively. Remember to leverage the .trigger command for most scenarios and reserve .capture for special cases where you need to intercept events earlier in the event propagation cycle. With these tools, you can craft a seamless user experience that responds to every click, keypress, and interaction.

Text interpolation allows you to display values within your template views. By leveraging ${}, a dollar sign followed by opening and closing curly braces, you can display values inside your views. The syntax will be familiar to you if you are familiar with template literals.

Displaying values with interpolation

Interpolation can be used to display the value of variables within your HTML templates, object properties and other forms of valid data.

To show how interpolation works, here is an example.

export class MyApp {
  myName = 'Aurelia';
}

<p>Hello, my name is ${myName}</p>

Notice how the variable we reference in our HTML template is the same as it is defined inside of our view model? Anything specified on our view model class is accessible in the view. Aurelia will replace ${myName} with Aurelia think of it as a fancy string replacement. All properties defined in your view model will be accessible inside your templates.

Template expressions

A template expression allows you to perform code operations inside of ${} we learned about earlier. You can perform addition, subtraction and even call functions inside of interpolation.

In the following simple example, we are adding two and two together. The value that will be displayed will be 4.

<p>Quick maths: ${2 + 2}</p>

You can call functions with parameters if you have a function inside your view model.

export class MyApp {
  adder(val1, val2) {
    return parseInt(val1) + parseInt(val2);
  }
}

<p>Behold mathematics, 6 + 1 = ${adder(6, 1)}</p>

You can also use ternaries inside of your interpolation expressions:

<p>${isTrue ? 'True' : 'False'}</p>

Optional Syntax

Also supported in template expressions is optional syntax. Aurelia supports the following optional syntax in templates.

• ??

• ?.

• ?.()

• ?.[]

Using optional syntax and nullish coalescing allows us to create safer expressions without the need for if.bind or boilerplate code in view models.

${myValue ?? 'Some default'}

This can help clean up what otherwise might have been long and complex ternary expressions to achieve the above result.

Notes on syntax

You would be forgiven for thinking that you can do pretty much anything that Javascript allows you to do, but there are limitations in what you can do inside of interpolation you need to be aware of.

1. Expressions cannot be chained using ; or ,

2. You cannot use primitives such as Boolean, String, instanceOf, typeof and so on

3. You can only use the pipe separator | when using value converters but not as a bitwise operator

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

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

Infinity
NaN
isFinite
isNaN
parseFloat
parseInt
decodeURI
decodeURIComponent
encodeURI
encodeURIComponent
Array
BigInt
Boolean
Date
Map
Number
Object
RegExp
Set
String
JSON
Math
Intl

Global Examples

Here are some examples of using globals inside of Aurelia templates. The usage is the same as it is inside of Javascript, except in your Aurelia templates.

Working with JSON

Manipulate JSON data directly in your templates.

<template>
  <pre>${JSON.stringify(user, null, 2)}</pre>
</template>

Mathematical Operations

Perform calculations using the Math object.

<template>
  <p>The square root of 16 is ${Math.sqrt(16)}</p>
</template>

Conditional Rendering with isNaN

Display content conditionally based on numeric checks.

<template>
  <p if.bind="isNaN(value)">Not a number</p>
</template>

Regular Expressions with RegExp

Use the RegExp constructor to create dynamic regular expressions for data validation or manipulation.

<template>
  <input value.bind="email" type="email" placeholder="Enter email">
  <p if.bind="new RegExp('^\\S+@\\S+\\.\\S+$').test(email)">Valid Email Address</p>
</template>

Dynamic Object Property Access with Object

Access properties dynamically on an object using the Object constructor.

<template>
  <p>Property Value: ${Object.getOwnPropertyDescriptor(user, selectedProperty)?.value}</p>
</template>

Set Operations with Set

Demonstrate set operations like union, intersection, or difference.

<template>
  <p>Unique Numbers: ${[...new Set(numbersArray)]}</p>
</template>

Encoding and Decoding URLs with encodeURI and decodeURI

Manipulate URL strings by encoding or decoding them.

<template>
  <a href.bind="encodeURI(externalLink)">Visit External Site</a>
  <p>Original URL: ${decodeURI(externalLink)}</p>
</template>

Number Formatting with Intl.NumberFormat

Format numbers using Intl.NumberFormat for localization.

<template>
  <p>${new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(price)}</p>
</template>

Complex Array Manipulations with Array

Demonstrate complex array manipulations, such as chaining methods.

<template>
  <p>Processed Data: ${Array.from(dataSet).filter(x => x.isActive).map(x => x.value).join(', ')}</p>
</template>

Best Practices and Considerations

• Use Sparingly: Rely on global variables only when necessary. Prefer component properties and methods for data and logic.

• Security: Be cautious of the data processed using global functions to prevent XSS attacks and other vulnerabilities.

• Performance: Frequent use of complex operations like JSON.stringify in templates can impact performance. Consider handling such operations in the component class.

• Reactivity: Remember that changes to global variables are not reactive. If you need reactivity, use component properties or state management solutions.

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

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

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

Features of Aurelia Templating

• Two-Way Data Binding: Aurelia's robust data binding system ensures a seamless data flow between your application’s model and the view, keeping both in sync without extra effort.

• Custom Elements and Attributes: Extend your HTML with custom elements and attributes that encapsulate complex behaviors, promoting code reuse and modularity.

• Adaptive Dynamic Composition: Dynamically render components and templates based on your application's state or user interactions, enabling the creation of flexible and adaptive UIs.

• Rich Templating Syntax: Utilize Aurelia's powerful templating syntax for iterating over data, conditionally rendering parts of your UI, and easily handling events.

• Expression and Interpolation: Effortlessly bind data to your templates and manipulate attributes with Aurelia’s straightforward expression syntax.

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

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

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

You could then display this value using its camelCase variant:

<p>${someVar}</p>

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

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

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

A custom attribute allows you to create special properties to enhance and decorate existing HTML elements and components. Natively attributes exist in the form of things such as disabled on form inputs or aria text labels. Where custom attributes can be especially useful is wrapping existing HTML plugins that generate their own markup.

Creating custom attributes

On a simplistic level, custom attributes resemble components quite a lot. They can have bindable properties, and they use classes for their definitions.

A basic custom attribute looks something like this:

export class CustomPropertyCustomAttribute {
}

If you were to replace CustomAttribute with CustomElement, it would be a component. On a core level, custom attributes are a more primitive component form.

Let's create a custom attribute that adds a red background and height to any dom element it is used on:

  import { INode } from 'aurelia';
  
  export class RedSquareCustomAttribute {
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = 'red';
    }
  }

Now, let's use our custom attribute:

<import from="./red-square"></import>

<div red-square></div>

We import our custom attribute so the DI knows about it and then use it on an empty DIV. We'll have a red background element with a height of one hundred pixels.

Explicit custom attributes

The customAttribute decorator allows you to create custom attributes, including the name explicitly. Other configuration options include the ability to create aliases.

Explicit attribute naming

You can explicitly name the custom attribute using the name configuration property.

  import { customAttribute, INode } from 'aurelia';
  
  @customAttribute({ name: 'red-square' }) 
  export class RedSquare {
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = 'red';
    }
  }

Attribute aliases

The customAttribute allows you to create one or more aliases that this attribute can go by.

  import { customAttribute, INode } from 'aurelia';
  
  @customAttribute({ name: 'red-square', aliases: ['redify', 'redbox'] }) 
  export class RedSquare {
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = 'red';
    }
  }

We can now use our custom attribute using the registered name red-square as well as redify and redbox the following example highlights using both aliases on an element.

<div redify></div>

<div redbox></div>

Single value binding

Sometimes, you want a custom attribute with only one bindable property. You don't need to define the bindable property explicitly to do this, as Aurelia supports custom attributes with single-value bindings.

  import { INode } from 'aurelia';

  export class RedSquareCustomAttribute {
    private value;
    
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = 'red';
    }
    
    bind() {
        this.element.style.backgroundColor = this.value;
    }
  }

The value property is automatically populated if a value is supplied to a custom attribute, however, requires you to define the value property as a bindable explicitly.

When the value is changed, we can access it like this:

  import { bindable, INode } from 'aurelia';
  
  export class RedSquareCustomAttribute {
    @bindable() private value;
    
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = 'red';
    }
    
    bound() {
        this.element.style.backgroundColor = this.value;
    }
    
    valueChanged(newValue: string, oldValue: string){
        this.element.style.backgroundColor = newValue;
    }
  }

Accessing the element

When using the custom attribute on a dom element, there are instances where you want to be able to access the element itself. To do this, you can use the INode decorator and HTMLElement interface to inject and target the element.

  import { INode } from 'aurelia';
  
  export class RedSquareCustomAttribute {
    constructor(@INode private element: HTMLElement){

    }
  }

The code above was lifted from the first example, allowing us to access the element itself on the class using this.element This is how we can set CSS values and perform other modifications, such as initialising third-party libraries like jQuery and other libraries.

Custom attributes with bindable properties

In many cases, you might only need custom attributes without user-configurable properties. However, in some cases, you want the user to be able to pass in one or more properties to change the behavior of the custom attribute (like a plugin).

Using bindable properties, you can create a configurable custom attribute. Taking our example from above, let's make the background color configurable instead of always red. We will rename the attribute for this.

  import { bindable, INode } from 'aurelia';
  
  export class ColorSquareCustomAttribute {
    @bindable() color: string = 'red';
  
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = '100px';
        this.element.style.backgroundColor = this.color;
    }
    
    bound() {
      this.element.style.backgroundColor = this.color;
    }
  }

We can now provide a color on a per-use basis. Let's go one step further and allow the size to be set too.

  import { bindable, INode } from 'aurelia';
  
  export class ColorSquareCustomAttribute {
    @bindable() color: string = 'red';
    @bindable() size: string = '100px';
  
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = this.size;
        this.element.style.backgroundColor = this.color;
    }
    
    bound() {
      this.element.style.width = this.element.style.height = this.size;
      this.element.style.backgroundColor = this.color;
    }
}

Responding to bindable property change events

We have code that will work on the first initialization of our custom property, but if the property is changed after rendering, nothing else will happen. We need to use the change detection functionality to update the element when any bindable properties change.

  import { bindable, INode } from 'aurelia';
  
  export class ColorSquareCustomAttribute {
    @bindable() color: string = 'red';
    @bindable() size: string = '100px';
  
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = this.size;
        this.element.style.backgroundColor = this.color;
    }
    
    bound() {
      this.element.style.width = this.element.style.height = this.size;
      this.element.style.backgroundColor = this.color;
    }
    
    colorChanged(newColor, oldColor) {
      this.element.style.backgroundColor = newColor;
    }
    
    sizeChanged(newSize: string, oldSize: string) {
      this.element.style.width = this.element.style.height = newSize;
    }
}  

As a default convention, bindable property change callbacks will use the bindable property name followed by a suffix of Changed at the end. The change callback gets two parameters, the new value and the existing value.

Whenever our size or color bindable properties change, our element will be updated accordingly instead of only at render.

Options binding

Options binding provides a custom attribute with the ability to have multiple bindable properties. Each bindable property must be specified using the bindable decorator. The attribute view model may implement an optional ${propertyName}Changed(newValue, oldValue) callback function for each bindable property.

When binding to these options, separate each option with a semicolon and supply a binding command or literal value, as in the example below. It is important to note that bindable properties are converted to dash-case when used in the DOM, while the view model property they are bound to is kept with their original casing.

  import { bindable, INode } from 'aurelia';
  
  export class ColorSquareCustomAttribute {
    @bindable() color: string = 'red';
    @bindable() size: string = '100px';
  
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = this.size;
        this.element.style.backgroundColor = this.color;
    }
    
    bound() {
      this.element.style.width = this.element.style.height = this.size;
      this.element.style.backgroundColor = this.color;
    }
    
    colorChanged(newColor, oldColor) {
      this.element.style.backgroundColor = newColor;
    }
    
    sizeChanged(newSize: string, oldSize: string) {
      this.element.style.width = this.element.style.height = newSize;
    }
}  

To use options binding, here is how you might configure those properties:

<import from="./color-square"></import>

<div color-square="color.bind: myColor; size.bind: mySize;"></div>

Specifying a primary property

When you have more than one bindable property, you might want to specify which property is the primary one (if any). If you mostly expect the user only to configure one property most of the time, you can specify it is the primary property through the bindable configuration.

  import { bindable, INode } from 'aurelia';
   
  export class ColorSquareCustomAttribute {
    @bindable( {primary: true} ) color: string = 'red';
    @bindable() size: string = '100px';
  
    constructor(@INode private element: HTMLElement){
        this.element.style.width = this.element.style.height = this.size;
        this.element.style.backgroundColor = this.color;
    }
    
    bound() {
      this.element.style.width = this.element.style.height = this.size;
      this.element.style.backgroundColor = this.color;
    }
    
    colorChanged(newColor, oldColor) {
      this.element.style.backgroundColor = newColor;
    }
    
    sizeChanged(newSize, oldSize) {
      this.element.style.width = this.element.style.height = newSize;
    }
}  

The above example specifies that color is the primary bindable property. Our code actually doesn't change at all. The way we consume the custom attribute changes slightly.

<import from="./color-square"></import>

<div color-square="blue"></div>

Or, you can bind the value itself to the attribute:

<import from="./color-square"></import>

<div color-square.bind="myColour"></div>

What is Aurelia?

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

To start, jump to our Quick Start Guide or read on for an overview.

Why choose Aurelia?

Aurelia emerges as a beacon of innovation and power in front-end development in a sea of frameworks. Here's why Aurelia might be the perfect choice for your next project:

• All-in-One Ecosystem: Aurelia is your Swiss Army knife, offering everything from dependency injection to routing, eliminating the need to juggle multiple libraries. Its ecosystem extends to plugins for internationalization, validation, and more, supported by tools like a CLI and a VS Code plugin for seamless development. And with Aurelia, flexibility is key; you can customize every aspect, including the templating/binding engine.

• Unparalleled Performance: Speed and efficiency are in Aurelia's DNA. It consistently outperforms competitors in benchmarks thanks to its sophisticated batched rendering and efficient memory usage.

• Data-Binding Done Right: Aurelia harmonizes the safety of uni-directional data flow with data-binding productivity, ensuring both performance and ease of development.

• Stability in a Dynamic World: Since our 1.0 release in 2016, Aurelia has maintained API stability, innovating without breaking changes, a testament to our commitment to developer trust.

• Adherence to High Standards: Aurelia is a paragon of standards compliance, focusing on modern JavaScript and Web Components without unnecessary abstractions.

• Empowering Developers: Aurelia's philosophy is simple: empower developers with plain JavaScript/TypeScript and get out of the way. This results in cleaner, more maintainable code.

• Ease of Learning and Use: Aurelia's design is intuitive and consistent, minimizing the learning curve and maximizing productivity with solid, simple conventions.

• Seamless Integration: Aurelia plays well with others. Its adherence to web standards makes it a breeze to integrate with any third-party library or framework.

• A Vibrant Open-Source Community: Embrace the open-source ethos with Aurelia, licensed under MIT, without restrictive clauses. Join a community that thrives on collaboration and innovation.

• A Welcoming and Supportive Community: Our active core team and Discord server embody a culture of welcome and support, where every developer is a valued member of the Aurelia family.

Embracing a Boutique Ecosystem

While it's true that Aurelia's ecosystem and community might seem modest compared to some of its more populous counterparts, this perceived underdog status is, in fact, one of its greatest strengths. Aurelia represents a boutique choice in web frameworks, prioritizing quality over quantity and fostering a tight-knit, highly engaged community. This approach translates to a more focused, consistent, and dedicated development experience, both in terms of the framework itself and the support you receive from the community.

The Advantages of a Niche Community

• Direct Impact: In a smaller community, each member's voice and contribution have a more significant impact. Developers have direct access to the core team, fostering a collaborative environment where feedback and contributions influence the framework's evolution.

• Quality Over Quantity: Aurelia focuses on delivering a high-quality, refined development experience. This means that each plugin, library, and tool in the ecosystem has been carefully crafted and thoroughly vetted to meet high standards.

• Nurturing Innovation: A smaller ecosystem doesn't mean limited capabilities. On the contrary, it often leads to innovative solutions and creative problem-solving, as developers are encouraged to think outside the box.

• Stronger Connections: A smaller community fosters closer relationships, leading to more meaningful interactions, collaborations, and a sense of belonging. This environment is conducive to a supportive and helpful atmosphere where developers at all levels can thrive.

Why Size Isn't Everything

The size of a community or ecosystem should not be the sole criterion for its effectiveness. In many cases, the quality of interactions, the dedication of its members, and the framework's alignment with your project's needs are far more critical factors. Aurelia's commitment to standards, modern best practices, and empowering approach offers a unique and rewarding development experience that stands on its own merits. Aurelia isn't trying to reinvent the wheel or make your life a misery by changing its API with every major release.

The Power of Conventional DOM Manipulation: why Aurelia doesn't have a Virtual DOM

In a landscape where Virtual DOM is often touted as a necessity, Aurelia confidently takes a different path. Aurelia's choice not to use a Virtual DOM is a deliberate and strategic decision grounded in a philosophy that prioritizes efficiency, simplicity, and alignment with web standards.

Understanding the Conventional DOM Approach

• Directness and Efficiency: Aurelia interacts directly and efficiently with the DOM. By avoiding the overhead of a Virtual DOM, Aurelia ensures faster rendering and updates, leading to a smoother user experience.

• Simplicity and Predictability: Without the abstraction layer of a Virtual DOM, Aurelia offers a more straightforward and predictable development experience. Developers work closer to the web platform, leveraging native browser capabilities for DOM manipulation.

• Optimal Performance: Aurelia's approach to DOM updates is highly optimized. It intelligently manages DOM changes, ensuring minimal performance overhead. This results in applications that are not only fast but also more resource-efficient. Let's say Aurelia isn't going to drain your phone or Macbook Pro battery.

The Benefits of Conventional DOM in Aurelia

• Aligned with Web Standards: Aurelia's commitment to standards means that it leverages the native capabilities of modern browsers, ensuring compatibility and future-proofing your applications. If the browser can do it, Aurelia won't try one-upping it by rolling its own implementation.

• Less Complexity, More Control: By avoiding a Virtual DOM, Aurelia reduces the complexity of your application's architecture. This direct approach gives developers more control and understanding of how their application interacts with the browser.

• Tailored for Modern Web Development: Aurelia is designed to meet the needs of modern web applications. Its efficient, standards-based approach is perfectly suited for today's dynamic, interactive web experiences.

The decision to not use a Virtual DOM is a reflection of Aurelia's overarching philosophy: to provide a powerful, efficient, and straightforward framework that stays true to the nature of the web. This approach encourages developers to build applications that are both performant and maintainable, leveraging the full potential of the web platform.

Navigation The Aurelia Docs

Your journey with Aurelia begins here in our meticulously crafted documentation. Start with the Quick Start Guide to grasp the basics of building an Aurelia application. The "Getting Started" section is your next stop, followed by "App Basics" for a deep dive into regular Aurelia usage.

As your comfort with Aurelia grows, explore "Advanced Scenarios" for insights into performance optimization and large-scale project management. While you may find less need for raw API documentation due to Aurelia's convention-based approach, our "API" section is comprehensive. Don't miss the "Examples" section, where practical code samples for common scenarios are found. And, our "Resources" section is a treasure trove of FAQs, framework comparisons, and much more.

Did you find something amiss in our documentation? Every page includes an "Edit on GitHub" link, making it easy to contribute corrections or improvements.

How to Be Part of the Community

Where To Begin

You're in the right place. If you are starting with Aurelia, we highly recommend reading through our Quick Start Guide. It will show you how to create a project and build your first components using Aurelia's powerful templating system.

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

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.

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

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

Basic Example

The promise binding simplifies working with asynchronous data. It allows attributes to bind to various states of a promise: pending, resolved, and rejected.

<div promise.bind="promise1">
 <template pending>The promise is not yet settled.</template>
 <template then="data">The promise is resolved with ${data}.</template>
 <template catch="err">This promise is rejected with ${err.message}.</template>
</div>

<div promise.bind="promise2">
 <template pending>The promise is not yet settled.</template>
 <template then>The promise is resolved.</template>
 <template catch>This promise is rejected.</template>
</div>

Promise Binding Using Functions

The following example demonstrates a method fetchAdvice bound to the promise.bind attribute. It uses then and catch to handle resolved data and errors.

<let i.bind="0"></let>

<div promise.bind="fetchAdvice(i)">
  <span pending>Fetching advice...</span>
  <span then="data">
    Advice id: ${data.slip.id}<br>
    ${data.slip.advice}
    <button click.trigger="i = i+1">try again</button>
  </span>
  <span catch="err">
    Cannot get advice, error: ${err}
    <button click.trigger="i = i+1">try again</button>
  </span>
</div>

export class MyApp {
  fetchAdvice() {
    return fetch(
        "https://api.adviceslip.com/advice",
        {
          // This is not directly related to promise template controller.
          // This is simply to ensure that the example demonstrates the
          // change in data in every browser, without any confusion.
          cache: 'no-store'
        }
      )
      .then(r => r.ok
        ? r.json()
        : (() => { throw new Error('Unable to fetch NASA APOD data') })
      )
  }
}

This example can also be seen in action below.

Promise Bind Scope

The promise template controller operates within its own scope, preventing accidental pollution of the parent scope or view model.

<div promise.bind="promise">
 <foo-bar then="data" foo-data.bind="data"></foo-bar>
 <fizz-buzz catch="err" fizz-err.bind="err"></fizz-buzz>
</div>

In this example, data and err are scoped within the promise controller. To access these values in the view model, use $parent.data or $parent.err.

Nested Promise Bindings

Aurelia 2 supports nested promise bindings, allowing you to handle promises returned by other promises.

<template promise.bind="fetchPromise">
 <template pending>Fetching...</template>
 <template then="response" promise.bind="response.json()">
   <template then="data">${data}</template>
   <template catch>Deserialization error</template>
 </template>
 <template catch="err2">Cannot fetch</template>
</template>

Promise Bindings with repeat.for

When using promise.bind within a repeat.for, it's recommended to use a let binding to create a scoped context.

<let items.bind="[[42, true], ['foo-bar', false], ['forty-two', true], ['fizz-bazz', false]]"></let>
<template repeat.for="item of items">
  <template promise.bind="item[0] | promisify:item[1]">
    <let data.bind="null" err.bind="null"></let>
    <span then="data">${data}</span>
    <span catch="err">${err.message}</span>
  </template>
</template>

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

@valueConverter('promisify')
class Promisify {
  public toView(value: unknown, resolve: boolean = true): Promise<unknown> {
    return resolve ? Promise.resolve(value) : Promise.reject(new Error(String(value)));
  }
}

The above example shows usage involving repeat.for chained with a promisify value converter. Depending on the second boolean value, the value converter converts a simple value to a resolving or rejecting promise. The value converter in itself is not that important for this discussion. It is used to construct a repeat.for, promise combination easily.

The important thing to note here is the usage of let binding that forces the creation of two properties, namely data and err, in the overriding context, which gets higher precedence while binding.

Without these properties in the overriding context, the properties get created in the binding context, which eventually gets overwritten with the second iteration of the repeat. In short, with let binding in place, the output looks as follows.

<span>42</span>
<span>foo-bar</span>
<span>forty-two</span>
<span>fizz-bazz</span>

Use value converters to transform how values are displayed in your applications. You can use value converters to transform strings, format dates, currency display and other forms of manipulation. They can be used within interpolation and bindings, working with data to and from the view.

If you have worked with other libraries and frameworks, you might know value converters by another name; pipes.

Understanding value converter data flow

Most commonly, you'll create value converters that translate model data to a format suitable for the view; however, there are situations where you'll need to convert data from the view to a format expected by the view model, typically when using two-way binding with input elements.

toView

The toView method always receives the supplied value as the first argument, and subsequent parameters are configuration values (if applicable). This specifies what happens to values going to the view and allows you to modify them before display.

fromView

The fromView method always receives the supplied value as the first argument, and subsequent parameters are configuration values (if applicable). This specifies what happens to values going out of the view to the view model and allows you to modify them before the view model receives the changed value.

Using value converters

To apply a value converter, you use the pipe | character followed by the name of the value converter you want to use. If you have worked with Angular before, you would know value converters as pipes.

While Aurelia itself comes with no prebuilt value converters, this is what using them looks like for an imaginary value converter that converts a string to lowercase.

<h1>${someValue | toLowercase}</h1>

The code for this value converter might look something like this:

export class ToLowercaseValueConverter {
    toView(value) {
        return value.toLowerCase();
    }
}

Transforming data using multiple value converters and parameters

Multiple value converters

Value converters can be chained, meaning you can transform a value and then transform it through another value converter. To chain value converters, you separate your value converters using the pipe |. In this fictitious example, we are making our value lowercase and then running it through another value converter called bold which will wrap it in strong tags to make it bold.

<h1>${someValue | toLowercase | bold }</h1>

Parameter based value converters

You can also create value converters that accept one or more parameters. For value converters that format data, you might want to allow the developer to specify what that format is for, say, a currency or date formatting value converter.

Parameters are supplied using the colon : character, and like the pipe, for multiple parameters, you can chain them. Parameters can be supplied as one or more strings (passed to the value converter method as one or more arguments) or a singular object.

Static parameters

<h1>${someValue | date:'en-UK'}

Furthermore, value converter parameters also support bound values. Unlike other types of binding, you only have to supply the variable, which will bind it for you.

Bound parameters

<h1>${someValue | date:format}

export class MyApp {
    format = 'en-US';
}

Object parameters

If your value converter is going to have a lot of parameters, the existing approaches will fall apart quite quickly. You can specify your value converters take a single object of one or more parameters. Object parameters will also let you name them, unlike other parameters.

<ul>
    <li repeat.for="user of users | sort: { propertyName: 'age', direction: 'descending' }">${user.name}</li>
</ul>

On our fromView and toView methods, the second argument will be the supplied object we can reference.

Creating value converters

Create custom value converters that allow you to format how your data is displayed and retrieved in your views.

Like everything else in Aurelia, a value converter is a class. A value converter that doesn't do anything might look like this. Nothing about this example is Aurelia-specific and is valid in Javascript.

export class ThingValueConverter {
  toView(value) {
    return value;
  }
}

To teach you how value converters can be created, we will create a simplistic value converter called date, allowing us to format dates.

In this example, we will use a decorator valueConverter to decorate our class. While you can use the ValueConverter naming convention as we did above, it's important to learn the different ways you can create value converters.

import { valueConverter } from 'aurelia';

@valueConverter('date')
export class FormatDate {
  toView(value: string, locale = 'en-US') {
    const date = new Date(value);

    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat
    const format = Intl.DateTimeFormat(locale, {
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      timeZone: 'UTC'
    });

    if (Number.isNaN(date.valueOf())) {
      return 'Invalid Date';
    }

    return format.format(date);
  }
}

Import your value converter in your view

<import from="./date-value-converter" />

This example value below will display June 22, 2021 in your view. Because our default date format is US, it will display as month-date-year.

<p>${'2021-06-22T09:21:26.699Z' | date}</p>

The locale parameter we specified in our value converter supports a locale parameter, allowing us to change how our dates are displayed. Say you're in the UK or Australia. The default format is date-month-year.

<p>${'2021-06-22T09:21:26.699Z' | date:'en-GB'}</p>

To see our value converter in action, here is what it looks like:

Additional Value Converter Examples

To further highlight how useful value converters are, we will provide examples of different value converters you can use in your Aurelia applications.

Currency Formatting Converter

Formats a number as a currency string.

import { valueConverter } from 'aurelia';

@valueConverter('currencyFormat')
export class CurrencyFormatValueConverter {
  toView(value, locale = 'en-US', currency = 'USD') {
    return new Intl.NumberFormat(locale, {
      style: 'currency',
      currency: currency
    }).format(value);
  }
}

<p>Total: ${amount | currencyFormat:'en-US':'USD'}</p>

Emoji Converter

Converts specific keywords or phrases to emojis.

import { valueConverter } from 'aurelia';

@valueConverter('emoji')
export class EmojiConverter {
  private emojiMap = {
    "love": "❤️", "happy": "😊", "sad": "😢", 
    "angry": "😠", "coffee": "☕", "star": "⭐", 
    "cat": "🐱", "dog": "🐶", "pizza": "🍕"
  };

  toView(value: string) {
    return value.split(/\s+/).map(word => 
      this.emojiMap[word.toLowerCase()] || word
    ).join(' ');
  }
}

<p>${'I love coffee and pizza' | emoji}</p>

Leet Speak Converter

Converts regular text into 'leet' or '1337' speak, a form of internet slang.

import { valueConverter } from 'aurelia';

@valueConverter('leetSpeak')
export class LeetSpeakConverter {
  toView(value: string) {
    return value.replace(/a/gi, '4').replace(/e/gi, '3').replace(/l/gi, '1').replace(/t/gi, '7');
  }
}

<p>${'Aurelia is elite!' | leetSpeak}</p>

Upside Down Text Converter

Flips the text upside down.

import { valueConverter } from 'aurelia';

@valueConverter('upsideDown')
export class UpsideDownConverter {
  private flipMap = {
    'a': 'ɐ', 'b': 'q', 'c': 'ɔ', 'd': 'p', 'e': 'ǝ', 
    'f': 'ɟ', 'g': 'ƃ', 'h': 'ɥ', 'i': 'ᴉ', 'j': 'ɾ', 
    'k': 'ʞ', 'l': 'l', 'm': 'ɯ', 'n': 'u', 'o': 'o', 
    'p': 'd', 'q': 'b', 'r': 'ɹ', 's': 's', 't': 'ʇ', 
    'u': 'n', 'v': 'ʌ', 'w': 'ʍ', 'x': 'x', 'y': 'ʎ', 
    'z': 'z', 'A': '∀', 'B': '𐐒', 'C': 'Ɔ', 'D': 'ᗡ', 
    'E': 'Ǝ', 'F': 'Ⅎ', 'G': '⅁', 'H': 'H', 'I': 'I', 
    'J': 'ſ', 'K': 'Ʞ', 'L': '˥', 'M': 'W', 'N': 'N', 
    'O': 'O', 'P': 'Ԁ', 'Q': 'Q', 'R': 'ᴚ', 'S': 'S', 
    'T': '⊥', 'U': '∩', 'V': 'Λ', 'W': 'M', 'X': 'X', 
    'Y': '⅄', 'Z': 'Z', '1': 'Ɩ', '2': 'ᄅ', '3': 'Ɛ', 
    '4': 'ㄣ', '5': 'ϛ', '6': '9', '7': 'ㄥ', '8': '8', 
    '9': '6', '0': '0', '.': '˙', ',': "'", '?': '¿', 
    '!': '¡', '"': '„', "'": ',', '`': ',', '(': ')', 
    ')': '(', '[': ']', ']': '[', '{': '}', '}': '{', 
    '<': '>', '>': '<', '&': '⅋', '_': '‾'
  };

  toView(value: string) {
    return value.split('').map(char => 
      this.flipMap[char] || char
    ).reverse().join('');
  }
}

<p>${'Hello Aurelia!' | upsideDown}</p>

Ordinal Suffix Value Converter

Appends an ordinal suffix to a number (e.g., 1st, 2nd, 3rd, etc.).

import { valueConverter } from 'aurelia';

@valueConverter('ordinal')
export class OrdinalValueConverter {
  toView(value: number) {
    const suffixes = ["th", "st", "nd", "rd"];
    const v = value % 100;
    return value + (suffixes[(v - 20) % 10] || suffixes[v] || suffixes[0]);
  }
}

<p>${position | ordinal}</p>

Morse Code Converter

Converts text to Morse code.

import { valueConverter } from 'aurelia';

@valueConverter('morse')
export class MorseCodeValueConverter {
  private morseAlphabet = {
    "A": ".-",    "B": "-...",  "C": "-.-.",  "D": "-..",
    "E": ".",     "F": "..-.",  "G": "--.",   "H": "....",
    "I": "..",    "J": ".---",  "K": "-.-",   "L": ".-..",
    "M": "--",    "N": "-.",    "O": "---",   "P": ".--.",
    "Q": "--.-",  "R": ".-.",   "S": "...",   "T": "-",
    "U": "..-",   "V": "...-",  "W": ".--",   "X": "-..-",
    "Y": "-.--",  "Z": "--..",
    "1": ".----", "2": "..---", "3": "...--", "4": "....-",
    "5": ".....", "6": "-....", "7": "--...", "8": "---..",
    "9": "----.", "0": "-----",
  };

  toView(value: string) {
    return value.toUpperCase().split('').map(char => 
      this.morseAlphabet[char] || char
    ).join(' ');
  }
}

<p>${message | morse}</p>

These fun and unique value converters showcase the versatility of Aurelia's templating engine and provide an enjoyable and engaging way for developers to learn about custom value converters.

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

Binding HTML Classes

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

Binding to a single class

Adding or removing a single class value from an element can be done using the .class binding. By prefixing the .class binding with the name of the class you want to display conditionally selected.class="myBool" you can add a selected class to an element. The value you pass into this binding is a boolean value (either true or false), if it is true the class will be added; otherwise, it will be removed.

<p selected.class="isSelected">I am selected (I think)</p>

Inside of your view model, you would specify isSelected as a property and depending on the value, the class would be added or removed.

Here is a working example of a boolean value being toggled using .class bindings.

Binding to multiple classes

Unlike singular class binding, you cannot use the .class binding syntax to conditionally bind multiple CSS classes. However, there is a multitude of different ways in which this can be achieved.

Once you have your CSS imported and ready to use in your components, there might be instances where you want to dynamically bind to the style attribute on an element (think setting dynamic widths or backgrounds).

Binding Inline Styles

Binding to a single style

You can dynamically add a CSS style value to an element using the .style binding in Aurelia.

<p background.style="bg">My background is blue</p>

Inside of your view model, you would specify bg as a string value on your class.

Here is a working example of a style binding setting the background colour to blue:

Binding to multiple styles

To bind to one or more CSS style properties you can either use a string containing your style values (including dynamic values) or an object containing styles.

Style binding using strings

This is what a style string looks like, notice the interpolation here? It almost resembles just a plain native style attribute, with exception of the interpolation for certain values. Notice how you can also mix normal styles with interpolation as well?

export class MyApp {
  private backgroundColor = 'black';
  private textColor = '#FFF';
}

<p style="color: ${textColor}; font-weight: bold; background: ${backgroundColor};">Hello there</p>

You can also bind a string from your view model to the style property instead of inline string assignment by using style.bind="myString" where myString is a string of styles inside of your view model.

Style binding using objects

Styles can be passed into an element by binding to the styles property and using .bind to pass in an object of style properties. We can rewrite the above example to use style objects.

export class MyApp {
  private styleObject = {
    background: 'black',
    color: '#FFF'
  };
}

<p style.bind="styleObject">Hello there</p>

From a styling perspective, both examples above do the same thing. However, we are passing in an object and binding it to the style property instead of a string.

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

Using if.bind

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

When the bound value evaluates to false, Aurelia removes the element and its descendants from the DOM. This process includes the destruction of custom elements, detaching of events, and cleanup of any associated resources, which is beneficial for performance and memory management.

Consider an application where you want to display a loading message while data is being fetched:

The isLoading variable controls the presence of the div in the DOM. When it's true, the loading message appears; when false, the message is removed.

Complementing if.bind with else

Aurelia enables if/else structures in the view, similar to conditional statements in JavaScript. The else binding must immediately follow an element with if.bind:

This snippet displays a welcome message for authenticated users and a login prompt for others.

Performance Considerations

Be mindful that if.bind modifies the DOM structure, which can trigger reflow and repaint processes in the browser. For applications with extensive DOM manipulation, this may become a performance bottleneck. Optimize your usage of if.bind by minimizing the frequency and complexity of conditional rendering operations.

Employing show.bind

The show.bind directive offers an alternative approach to conditional rendering. Instead of adding or removing elements from the DOM, it toggles their visibility. This is akin to applying display: none; in CSS—the element remains in the DOM but is not visible to the user.

Here, isDataLoaded dictates the visibility of the message. When false, the message is hidden; when true, it is shown. All bindings and events remain intact since the element is not removed from the DOM.

Leveraging switch.bind

For more complex conditional rendering cases, such as when dealing with enumerated values, switch.bind is the ideal choice. It offers a clean, semantic way to handle multiple conditions by mimicking the switch statement in JavaScript.

For instance, given an enumeration of order statuses:

Displaying a message based on the order status with if.bind can become unwieldy. Instead, switch.bind offers a concise and clear approach:

This structure allows for a straightforward mapping between the status and the corresponding message. The default-case acts as a catch-all for any status not explicitly handled.

Grouping Cases

You can bind an array of values to a case, thus grouping multiple conditions:

This will display "Order is being processed." for both Received and Processing statuses.

Fall-Through Behavior

The switch construct in Aurelia supports fall-through logic similar to JavaScript's switch:

When orderStatus is Received, both the "Order received." and "Order is being processed." messages will be displayed because of the fall-through attribute.

Advanced Scenarios with switch.bind

Aurelia's switch.bind can accommodate various advanced use cases, making it a versatile tool for conditional rendering. Below are examples of such scenarios:

Using switch.bind with Static Expressions

You can use switch.bind with a static expression, while the case.bind attributes feature more dynamic conditions:

This example iterates over numbers 0 to 99 and applies the FizzBuzz logic, displaying "Fizz", "Buzz", or "FizzBuzz" depending on whether the number is divisible by 3, 5, or both.

Conditional Slot Projection with switch.bind

switch.bind can be combined with au-slot to project content into custom elements conditionally:

In this case, the custom element foo-bar will project different messages based on the status value.

Nesting switch.bind

switch.bind can be nested within itself for complex conditional logic:

This example demonstrates how you can use nested switch.bind statements to handle multiple levels of conditional rendering.

Restrictions on case Usage

The case attribute must be used within the context of a switch and should be its direct child. The following are examples of incorrect and unsupported usages:

These examples will either throw an error or result in unexpected behavior. If you need to support a use case like this, consider reaching out to the Aurelia team.

By exploring these advanced scenarios, you can harness the full potential of switch.bind to address complex conditional rendering needs in your Aurelia applications. Remember to adhere to the guidelines and limitations to ensure proper functionality and maintainability.

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

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

Throttle

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

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

Updating a property, at most, every 200ms

HTML

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

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

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

• Binding expressions can also include a combination of value converters and binding behaviors: ${foo | upperCase | truncate:3 & throttle & anotherBehavior:arg1:arg2}.

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

Updating a property, at most, every 850ms

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

Handling an event, at most, every 200ms

Flush pending throttled calls

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

Debounce

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

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

Update after typing stopped for 200ms

Update after typing stopped for 850ms

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

Here's another example with the mousemove event:

Call mouseMove after the mouse stops moving for 500ms

Flush pending debounced calls

UpdateTrigger

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

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

Update on blur

Multiple events are supported:

Update with multiple events

Signal

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

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

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

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

Using a Signal

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

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

Signaling Bindings

oneTime

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

One-time String Interpolation

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

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

To-view and two-way binding behaviours

Self

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

For example, in the following markup

Self-binding behavior

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

Handler without self-binding behavior

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

Using self-binding behavior

Using self-binding behavior

Custom binding behaviors

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

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

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

Log Binding Behavior

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

Tooltip Binding Behavior

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

Highlight Updates Binding Behavior

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

Aurelia supports working with different types of data. Array, Set, and Map are all supported collection types that can be iterated in your templates.

repeat.for

You can use the repeat.for binding to iterate over data collections in your templates. Think of repeat.for as a for loop. It can iterate arrays, maps and sets.

Breaking this intuitive syntax down, it works like this:

• Loop over every item in the items array

• Store each iterative value in the local variable item on the left-hand side

• For each iteration, make the current item available

If you were to write the above in Javascript form, it would look like this:

Keyed iteration

When working with the repeat.for attribute in Aurelia, the key attribute specifies the property that uniquely identifies each item in the collection. Aurelia uses this property to track changes in the collection and efficiently update the DOM accordingly.

To use the key attribute, add it to the repeater element and bind it to a unique property of each item in the collection. You can use either literal or expression syntax:

In this example, id is the property name Aurelia will use to uniquely identify each item in the items collection.

The key attribute serves the following purposes:

• Change Tracking: Aurelia tracks changes in the collection using the specified property. When an item is added, removed, or reordered, Aurelia compares the key property values to determine which items have changed.

• Minimal DOM Updates: Aurelia can minimize the number of DOM manipulations required when updating the rendered list by tracking changes based on the key property. It can reuse existing elements and only make necessary changes.

• Preservation of Element State: When an item's position in the collection changes, Aurelia can preserve the state of the corresponding rendered element (such as focus, scroll position, or user input) by matching the key property values.

Choosing the key Property

When selecting the property to use as the key, consider the following guidelines:

• The property should have unique values for each item in the collection.

• The property should be stable and not change over time for a given item.

• Avoid using the item's index as the key unless the collection is static and the order of items does not change.

Common choices for the key property include unique identifiers like ID or a combination of properties that uniquely identify an item.

The key attribute in Aurelia repeaters specifies the property that uniquely identifies each collection item. By setting the key attribute, Aurelia can track changes, update the DOM, and preserve the element state when rendering dynamic lists.

Choose a property that provides unique and stable values for each item in the collection to ensure optimal performance and avoid unwanted side effects.

Index and Contextual properties inside of repeat.for

Aurelia's binding engine makes several special properties available in your binding expressions. Some properties are available everywhere, while others are only available in a particular context.

Below is a summary of the available contextual properties within repeats.

$index

In a repeat template, the item's index is in the collection. The index is zero-indexed, meaning the value starts from zero and increments by one for each iteration in the repeat.for loop. The following example $index will be 0 for the first iteration, then 1 and so forth.

$first

In a repeat template, the $first variable will be true if this is the first iteration in the repeat.for loop. If the iteration is not the first iteration, then this value will be false.

$last

In a repeat template the $last variable will be true if this is the last iteration in the repeat.for loop. This means we have reached the final item in the collection we are iterating. If the loop is continuing, this value will be false.

$even

In a repeat template the $even variable will be true if we are currently at an even-numbered index inside the repeat.for loop. You would use this functionality when performing conditional logic (alternate row styling on table rows and so forth).

$odd

In a repeat template, the $odd variable will be true if we are currently at an odd-numbered index inside the repeat.for loop. You would use this functionality when performing conditional logic (alternate row styling on table rows).

$length

In a repeat template the $length variable will provide the length of the collection being iterated. This value should not change throughout iterating over the collection and represents the length of the collection akin to (Array.length).

$parent

Explicitly accesses the outer scope from within a repeat.for template. In most instances where you are dealing with the value of the collection you are iterating, the $parent variable will not be needed.

You may need this when a property on the current scope masks a property on the outer scope. Note that this property is chainable, e.g. $parent.$parent.foo is supported.

These can be accessed inside the repeat.for. In the following example, we display the current index value.

You would need this functionality when dealing with multiple levels of repeat.for aka nested repeaters. As each repeat.for creates its own scope, you need to use $parent to access the outer scope of the repeater.t

Array Syntax

In this section, see how you can iterate an array using repeat.for. You will notice the syntax is the same as the examples we used above, except for a view model containing the array to show you the relationship.

Ranges Syntax

The repeat.for functionality doesn't just allow you to work with collections. It can be used to generate ranges.

In the following example, we generate a range of numbers up to 10. We subtract the value from the index inside to create a reverse countdown.

Set Syntax

The repeat.for functionality works with arrays (the collection type you will be using) and Javascript sets. The syntax for iterating sets is the same as for arrays, so nothing changes in the template, only the collection type you are working with.

Map Syntax

One of the more useful iterables is the Map because you can directly decompose your key and value into two variables in the repeater. Although you can repeat over objects straightforwardly, Maps can be two-way bound easier than Objects, so you should try to use Maps where possible.

Please take note of the syntax in our template. Unlike repeat.for usage for Arrays and Sets, we are decomposing the key and value (as we discussed) on the repeater itself. The syntax is still familiar but slightly different.

One thing to notice in the example above is the dereference operator in [greeting, friend] - which breaks apart the map's key-value pair into greeting, the key, and friend, the value. Note that because all of our values are objects with the name property set, we can get our friend's name with ${friend.name}, just as if we were getting it from JavaScript!

Object Syntax

Create a value converter

We take the object in our view model, friends, and run it through our keys value converter. Aurelia looks for a registered class named KeysValueConverter and tries to call its toView() method with our friend's object. That method returns an array of keys- which we can iterate.

Our value converter uses the Javascript Reflect API to get the keys of our object, returning the values in an iterable format that our repeat.for can understand. In our template, we import our value converter to use it.

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

Declaring Template References

Basic Usage

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

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

Accessing Reference in Template

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

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

Accessing Reference in View Model

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

Advanced Usage

Working with Custom Elements and Attributes

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

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

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

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

Practical Applications

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

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:

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

Array methods with repeat.for

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

Previously, to filter some array items in a repeater, you might have written something like this using a value converter:

While there is nothing wrong with value converters, and in some situations, they might be preferable (especially for testing), you can achieve the same thing without writing any additional code like this:

We are calling a callback function called isGood defined inside our template to determine if the item is filtered.

Filter and Sort

Observation-wise, Aurelia knows only to observe selected property of every item in items, as well as pos property of every selected item. This means changing the value of selected property of any item will result in the re-evaluation of the above expression. Changing the value of pos property of any selected item will also trigger the re-evaluation. Aurelia will also subscribe to the mutation of the array items to refresh this binding.

As we might have inside of a value converter, we use two Javascript functions, filter and sort — Aurelia's lambda expression support means we can chain these functions without needing to write any code in a view-model or value converter.

Event Callbacks

With arrow functions, we can express the following:

As the following:

As a result, .call is being deprecated in Aurelia as the lambda expression syntax allows us to handle this in a more JavaScript way.

Interpolation Expressions

Not only are lambda functions supported in a repeat.for, but we can also use them in interpolation expressions.

Map

Say you have an array of keywords for an item, and you want to display those as a comma-separated list. Previously, you would have used a value converter or function in your view model to achieve this task. Now, you can do it from within your templates.

Reduce

Another task might be to take an array of items (say, products in a cart) and then calculate the total. Once again, we might have previously used a value converter or computed getter for this task, but now we can use reduce in our template.

Valid Uses

While a broad syntax for lambda expressions is supported, here is a list of valid uses.

Invalid Uses

The following uses of lambda expressions are not supported in Aurelia templates.

Examples

Now we understand what lambda expressions are and how they can be used, here are some examples of how you might leverage them in your Aurelia applications.

Inline Array Transformation and Display

Transform and display an array of objects inline, such as a list of names.

Complex Object Filtering

Use lambda expressions for complex filtering, such as filtering based on multiple object properties.

Event Handling with Additional Context

Handle events with additional context passed to the event handler.

Nested Array Operations

Perform operations on nested arrays, such as displaying a flattened list of sub-items.

Combining Multiple Array Methods

Chain multiple array methods for data processing.

Using Reduce for Total Calculation

Calculate the total price of items in a shopping cart.

Creating a Comma-Separated List

Transform an array of objects into a comma-separated list.

Calculating an Aggregate Property

Use reduce to calculate an aggregate property, such as the average age.

Using includes for Conditional Rendering

Check if an array includes a certain value and conditionally render content.

Dynamic Class Assignment with includes

Assign a class to an element if an array includes a specific item.

Finding an Item with find

Display details of the first item that matches a condition.

Using find in Event Handling

Use find in an event handling expression to work with a specific item.

Nested Arrays with flat

Flatten a nested array and display its contents.

Displaying a Flattened List of Attributes

Use flat to create a flattened list of attributes from an array of objects.

Introduction

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

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

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

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

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

Why use local templates

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

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

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

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

Features and pitfalls

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

Local templates are hoisted.

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

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

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

Custom elements cannot contain only local templates

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

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

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

Local templates need to have a name

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

Local template names need to be unique

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

Bindable tags need to be under the local template root

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

The property attribute on bindable tags is mandatory

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

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.

Download a code editor

Create a new Aurelia project

Open up a Terminal/Command Prompt window and run the following:

You are going to be presented with a few options when you run this command. Don't worry, we'll go through each screen step by step.

Step 1. Name your project

You will be asked to enter a name for your project, this can be anything you want. If you can't think of a name just enter my-app and then hit enter.

Step 2. Choose your options

In step 2 you will be presented with three options.

• Option one: "Default ESNext Aurelia 2 App" this is a basic Aurelia 2 Javascript application using Babel for transpiling and Webpack for the bundler.

• Option two: "Default Typescript Aurelia 2 App" this is a basic Aurelia 2 TypeScript application with Webpack for the bundler.

• Option three: "Custom Aurelia 2 App" no defaults, you choose everything.

In this guide, we are going to go with the most straightforward option, option #1.

Step 3. Install the dependencies

You are going to be asked if you want to install the Npm dependencies and the answer is yes. For this guide we are using Npm, so select option #2.

Depending on your internet connection speed, this can take a while.

Step 4. Run the sample app

After the installation is finished you should see a little block of text with the heading, "Get Started" follow the instructions. Firstly, cd my-app to go into the directory where we installed our app. Then run npm start to run our example app.

Your web browser should open automatically and point to http://localhost:9000

Any changes you make to the files in the src directory of your app will cause the dev server to refresh the page with your new changes. Edit my-app.html and save it to see the browser update. Cool!

Building your app

In the last section we created a new application and ran the development server, but in the "real world" you will build and deploy your site for production.

Run the Npm build command by running the following in your Terminal or Command Prompt window:

This will build your application for production and create a new folder called dist.

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.

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:

1. The user types a value into the input element. The element is for a first name, so they enter John.

2. The native form input events are fired, and Aurelia also sees the value has changed.

3. The binding system sees the new value and notifies the view model to update the value.

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

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:

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

2. Define each radio's value using the model property.

3. 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:

1. Add a <select> element to the template and decide whether the multiple attribute should be applied.

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

3. Define the select element's <option> elements. You can use repeat or add each option element manually.

4. Specify each option's value via the model property:

   <option model.bind="product.id">${product.name}</option>

   You can use the standard value attribute instead of model, remember- it will coerce anything it's assigned to a string.

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.

Custom elements are the foundation of Aurelia applications. As a developer, you'll often create custom elements that consist of:

• An HTML template (view)

• A class acting as the view model

• An optional CSS stylesheet

There are various ways to create custom components in Aurelia, from simple convention-based components to more explicit and configurable ones.

The creation process is flexible, allowing you to adopt the approach that best fits your project's needs.

Creating Components

Aurelia treats any exported JavaScript class as a component by default. As such, there's no difference between an Aurelia component and a vanilla JavaScript class at their core.

Here's an example of a basic Aurelia component. You might add logic and bindable properties as needed, but at its simplest, a component is just a class.

By convention, Aurelia pairs the app-loader.ts view model with a corresponding app-loader.html file.

Explicit Component Creation with @customElement

The @customElement decorator provides a way to define components, bypassing conventions explicitly.

The @customElement decorator allows for a variety of customizations, such as defining a different HTML template or inline template string, specifying the element's tag name, and configuring other component properties that would otherwise be managed by Aurelia.

Here's an example of defining the template inline:

This approach is useful for simple components that don't require a separate view file.

Configuring the @customElement Decorator

The @customElement decorator allows for several configuration options:

name

This option sets the HTML tag name for the component. For instance, specifying "app-loader" means the component can be used in views as <app-loader></app-loader>.

If you only need to set the name, you can use a simpler syntax:

template

The template option allows you to define the content of your component's template. You can specify an external template file, an inline template string, or even set it to null for components that don't require a view:

Omitting the template property means Aurelia won't use conventions to locate the template.

dependencies

You can declare explicit dependencies within the @customElement decorator, which can be an explicit way to manage dependencies without using the <import> tag in your templates:

Programmatic Component Creation

Aurelia provides an API for creating components programmatically, which is especially useful for testing.

The CustomElement.define method allows for a syntax similar to the @customElement decorator, including dependencies and other configurations.

HTML-Only Components

It's possible to create components in Aurelia using only HTML without a corresponding view model.

For instance, an HTML-only loader component might look like this:

To use this component, import and reference it:

HTML Components with Bindable Properties

You can create HTML components with bindable properties using the <bindable> custom element, which serves a similar purpose to the @bindable decorator in a view model:

Here's how you would use it:

Components Without Views

Though less common, there are times when you might need a component with a view model but no view. Aurelia allows for this with the @customElement decorator by omitting the template property.

For example, a loading indicator using the nprogress library might be implemented as follows:

In this example, nprogress manages the DOM manipulation, so a template isn't necessary.

Registering Your Components

To use your custom components, you must register them either globally or within the scope of their intended use.

Globally Registering a Component

Register a component globally in main.ts using the .register method:

Importing a Component Within a Template

To use a component within a specific template, import it using the <import> tag:

To use a component but with an alias, import it using the <import> tag, together with the as attribute for the new name:

To use alias for a specific resource on an import, using the <import> tag, together with the {name}.as attribute for the new name, with {name} being the resource name:

Containerless Components

Sometimes you may want to render a component without its enclosing tags, effectively making it "containerless."

Using the @customElement Decorator

Mark a component as containerless with the containerless property:

The @containerless Decorator

The @containerless decorator is an alternative way to indicate a containerless component:

When using <my-component></my-component>, Aurelia will remove the surrounding tags, leaving only the inner content.

Containerless Elements in Views

Declare a containerless component inside a view using the <containerless> tag: