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.

The easiest way to install Node.js is from the official website here. Download the installer for your operating system and then follow the prompts.

Download a code editor

To write code, you need an editor that will help you. The most popular choice for Javascript development is Visual Studio Code. It is a completely free and open-source code editor made by Microsoft, which has great support for Aurelia applications and Node.js.

Create a new Aurelia project

We will be following the instructions in the Quick install guide to bootstrap a new Aurelia application. After installing Node.js, that's it. You don't need to install anything else to create a new Aurelia application, here's how we do it.

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

npx makes aurelia

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:

npm run build

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

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.

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

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

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.

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

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.

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

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

Firstly, let's write the code to display the value. Notice how we are using interpolation to print the value like the default generated my-app.html file was? ${name} the value inside the curly braces references the class property we defined in the previous section, by the name of name.

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

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

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

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

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

Binding the name to a text input

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

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

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

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

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.

Aurelia 2's templating system is the cornerstone of crafting rich, interactive user interfaces for your web applications. It transcends the limitations of static HTML, empowering you to create truly dynamic views that respond intelligently to both application data and user interactions. At its core, Aurelia templating establishes a fluid and intuitive connection between your HTML templates and your application logic written in JavaScript or TypeScript, resulting in a responsive and data-driven UI development experience.

Forget static HTML pages. Aurelia 2 templates are living, breathing views that actively engage with your application's underlying code. They react in real-time to data modifications and user actions, ensuring your UI is always in sync and providing a seamless user experience. This deep integration not only streamlines your development workflow but also significantly reduces boilerplate, allowing you to build sophisticated UIs with greater clarity and efficiency.

From the moment you initiate an Aurelia 2 project, you'll find yourself working with templates that are both comfortably familiar in their HTML structure and remarkably powerful in their extended capabilities. Whether you're structuring the layout for a complex component or simply displaying data within your HTML, Aurelia 2's templating syntax is meticulously designed to be both highly expressive and exceptionally developer-friendly, making UI development a truly enjoyable and productive process.

Key Features of Aurelia Templating

Aurelia's templating engine is packed with features designed to enhance your UI development workflow and capabilities:

• Effortless Two-Way Data Binding: Experience truly seamless synchronization between your application's data model and the rendered view. Aurelia's robust two-way data binding automatically keeps your model and UI in perfect harmony, eliminating manual DOM manipulation and ensuring data consistency with minimal effort.

• Extendable HTML with Custom Elements and Attributes: Break free from standard HTML limitations by creating your own reusable components and HTML attributes. Encapsulate complex UI logic and behavior into custom elements and attributes, promoting modularity, code reuse, and a more maintainable codebase. This allows you to tailor HTML to the specific needs of your application.

• Adaptive Dynamic Composition for Flexible UIs: Build truly dynamic and adaptable user interfaces with Aurelia's dynamic composition. Render different components and templates on-the-fly based on your application's state, user interactions, or any dynamic condition. This enables you to create flexible layouts and UI structures that respond intelligently to changing requirements.

• Expressive and Intuitive Templating Syntax: Harness the power of Aurelia's rich templating syntax to handle common UI patterns with ease. From iterating over lists of data and conditionally rendering UI elements to effortlessly managing user events, Aurelia's syntax is designed to be both powerful and remarkably intuitive, reducing complexity and boosting productivity.

• Simplified Data Integration with Expressions and Interpolation: Seamlessly integrate your application data into your templates using Aurelia's straightforward expression syntax. Effortlessly bind data to HTML elements and manipulate attributes directly within your templates using interpolation, making data display and interaction a breeze.

Aurelia 2's templating system is more than just a way to write HTML; it's a comprehensive toolkit for building modern, dynamic web applications with efficiency and elegance. By embracing its features, you'll unlock a more productive and enjoyable UI development experience.

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.

Text interpolation allows you to display dynamic values in your views. By wrapping an expression with ${}, you can render variables, object properties, function results, and more within your HTML. This is conceptually similar to JavaScript template literals.

Displaying values with interpolation

Interpolation can display the values of view model properties, object fields, and any valid expression. As an example, consider the following code:

export class MyApp {
  myName = 'Aurelia';
}

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

Here, the template references the same property name, myName, that is defined in the view model. Aurelia automatically replaces ${myName} with "Aurelia" at runtime. Any property you define on your class can be directly accessed inside your templates.

Template expressions

Expressions inside ${} can perform operations such as arithmetic, function calls, or ternaries:

<p>Quick maths: ${2 + 2}</p>
<!-- Outputs "Quick maths: 4" -->

Calling functions

You can call functions defined on your view model. For example:

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

<p>Behold mathematics, 6 + 1 = ${adder(6, 1)}</p>
<!-- Outputs "Behold mathematics, 6 + 1 = 7" -->

Using ternaries

You can also use ternary operations:

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

This will display either "True" or "False" depending on the boolean value of isTrue.

Optional Syntax

Aurelia supports the following optional chaining and nullish coalescing operators in templates:

• ??

• ?.

• ?.()

• ?.[]

You can use these operators to safely handle null or undefined values:

<p>User Name: ${user?.name ?? 'Anonymous'}</p>

This helps avoid lengthy if-statements or ternary checks in your view model when dealing with potentially undefined data.

Notes on syntax

While template interpolation is powerful, there are a few limitations to keep in mind:

1. You cannot chain expressions using ; or ,.

2. You cannot use certain primitives or operators such as Boolean, String, instanceof, or typeof.

3. The pipe character | is reserved for Aurelia value converters and cannot be used as a bitwise operator inside interpolation.

Attribute binding in Aurelia is a powerful feature that allows you to dynamically bind data from your view model to any native HTML attribute within your templates. This enables real-time updates to element attributes such as classes, styles, src, alt, and other standard HTML attributes, enhancing the interactivity and responsiveness of your applications.

Basic Binding Syntax

The fundamental syntax for binding to attributes in Aurelia is simple and intuitive:

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

• attribute-name.bind="value": The binding declaration.

  • attribute-name: The target HTML attribute you want to bind to.

  • .bind: The binding command indicating a two-way binding by default.

  • value: The expression or property from the view model to bind.

You can bind to virtually any attribute listed in the HTML Attributes Reference.

Example: Binding the title Attribute

<!-- my-app.html -->
<div title.bind="tooltipText">Hover over me!</div>

// my-app.ts
export class MyApp {
  tooltipText = 'This is a tooltip';
}

Result: The div will have a title attribute with the value "This is a tooltip". Hovering over the div will display the tooltip.

Binding Techniques and Syntax

Aurelia provides multiple methods for attribute binding, each tailored for specific use cases and offering different levels of data flow control.

1. Interpolation Binding

Interpolation allows embedding dynamic values directly within strings. This is useful for concatenating strings with dynamic data.

Example: Binding the id Attribute Using Interpolation

<!-- my-app.html -->
<div>
  <h1 id="${headingId}">Dynamic Heading</h1>
</div>

// my-app.ts
export class MyApp {
  headingId = 'main-heading';
}

Result: The h1 element will have an id attribute set to "main-heading".

2. Keyword Binding

Aurelia supports several binding keywords that define the direction and frequency of data flow between the view model and the view:

• .one-time: Updates the view from the view model only once. Subsequent changes in the view model do not affect the view.

• .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: Establishes a two-way data flow, keeping both the view and view model in sync.

• .bind: Automatically determines the appropriate binding mode. Defaults to .two-way for form elements (e.g., input, textarea) and .to-view for most other elements.

Examples of Keyword Binding

<!-- my-app.html -->
<!-- Two-way binding: changes in input update 'firstName' and vice versa -->
<input type="text" value.two-way="firstName" placeholder="First Name">

<!-- One-way binding: changes in 'lastName' update the input, but not vice versa -->
<input type="text" value.one-way="lastName" placeholder="Last Name">

<!-- One-time binding: input value is set once from 'middleName' -->
<input type="text" value.one-time="middleName" placeholder="Middle Name">

<!-- Binding a link's href attribute using to-view -->
<a href.to-view="profile.blogUrl">Blog</a>

<!-- Binding a link's href attribute using one-time -->
<a href.one-time="profile.twitterUrl">Twitter</a>

<!-- Binding a link's href attribute using bind (auto mode) -->
<a href.bind="profile.linkedInUrl">LinkedIn</a>

// my-app.ts
export class MyApp {
  firstName = 'John';
  lastName = 'Doe';
  middleName = 'A.';
  profile = {
    blogUrl: 'https://johnsblog.com',
    twitterUrl: 'https://twitter.com/johndoe',
    linkedInUrl: 'https://linkedin.com/in/johndoe'
  };
}

Result: The input fields and links will reflect the bound properties with varying degrees of reactivity based on the binding keyword used.

3. Binding to Images

Binding image attributes such as src and alt ensures that images update dynamically based on the view model data.

Example: Dynamic Image Binding

<!-- my-app.html -->
<img src.bind="imageSrc" alt.bind="imageAlt" />

// my-app.ts
export class MyApp {
  imageSrc = 'https://example.com/image.jpg';
  imageAlt = 'Example Image';
}

Result: The img element will display the image from the specified src and use the provided alt text.

4. Disabling Elements

Dynamically enabling or disabling form elements enhances user interaction and form validation.

Example: Binding the disabled Attribute

<!-- my-app.html -->
<button disabled.bind="isButtonDisabled">Submit</button>
<input type="text" disabled.bind="isInputDisabled" placeholder="Enter text" />

// my-app.ts
export class MyApp {
  isButtonDisabled = true;
  isInputDisabled = false;
  
  toggleButton() {
    this.isButtonDisabled = !this.isButtonDisabled;
  }
  
  toggleInput() {
    this.isInputDisabled = !this.isInputDisabled;
  }
}

Result: The Submit button starts as disabled, and the input field is enabled. Calling toggleButton() or toggleInput() will toggle their disabled states.

5. Binding innerHTML and textContent

Choose between innerHTML for rendering HTML content and textContent for rendering plain text to control how content is displayed within elements.

Example: Rendering HTML vs. Text

<!-- my-app.html -->
<div innerhtml.bind="htmlContent"></div>
<div textcontent.bind="plainText"></div>

// my-app.ts
export class MyApp {
  htmlContent = '<strong>This is bold text.</strong>';
  plainText = '<strong>This is not bold text.</strong>';
}

Result:

• The first div will render the bold text as HTML.

• The second div will display the HTML tags as plain text.

Advanced Binding Techniques

Explore more sophisticated binding scenarios to handle complex data interactions and ensure seamless attribute management.

1. How Attribute Binding Works

Aurelia employs a mapping function to translate view model properties to corresponding HTML attributes. This typically involves converting kebab-case attribute names to camelCase property names. However, not all properties directly map to attributes, especially custom or non-standard attributes.

Example: Automatic Mapping

<!-- my-app.html -->
<input value.bind="userName" />

// my-app.ts
export class MyApp {
  userName = 'JaneDoe';
}

Result: The input element's value attribute is bound to the userName property. Changes in userName update the input value and vice versa.

2. Using the .attr Binding Command

When automatic mapping fails or when dealing with non-standard attributes, use the .attr binding command to ensure proper attribute binding.

Example: Binding a Custom Attribute

<!-- my-app.html -->
<input my-custom-attr.attr="customValue" />

// my-app.ts
export class MyApp {
  customValue = 'Custom Attribute Value';
}

Result: The input element will have a my-custom-attr attribute set to "Custom Attribute Value".

3. Combining .bind with Attribute Binding Behavior

You can specify binding behaviors to fine-tune how bindings operate. For instance, using .bind with the attr binding behavior ensures that the binding targets the attribute rather than the property.

Example: Explicit Attribute Binding

<!-- my-app.html -->
<input pattern.bind="patternProp & attr" />

// my-app.ts
export class MyApp {
  patternProp = '[A-Za-z]{3,}';
}

Result: The input element's pattern attribute is bound to patternProp, ensuring that it reflects directly as an attribute in the DOM.

Practical Use Cases

To better illustrate attribute bindings, here are several practical scenarios showcasing different binding techniques.

1. Dynamic Class Binding

Example: Toggling CSS Classes

<!-- my-app.html -->
<div class.bind="isActive ? 'active' : 'inactive'">Status</div>

// my-app.ts
export class MyApp {
  isActive = true;
  
  toggleStatus() {
    this.isActive = !this.isActive;
  }
}

Result: The div will have the class active when isActive is true and inactive when false. Calling toggleStatus() toggles the class.

2. Styling Elements Dynamically

Example: Binding Inline Styles

<!-- my-app.html -->
<div style.backgroundColor.bind="bgColor">Colored Box</div>

// my-app.ts
export class MyApp {
  bgColor = 'lightblue';
  
  changeColor(newColor: string) {
    this.bgColor = newColor;
  }
}

Result: The div's background color reflects the current value of bgColor. Invoking changeColor('coral') will update the background to coral.

3. Conditional Attribute Rendering

Example: Conditionally Setting the required Attribute

<!-- my-app.html -->
<input type="email" required.bind="isEmailRequired" placeholder="Enter your email" />

// my-app.ts
export class MyApp {
  isEmailRequired = true;
  
  toggleEmailRequirement() {
    this.isEmailRequired = !this.isEmailRequired;
  }
}

Result: The input field will be required based on the isEmailRequired property. Toggling this property will add or remove the required attribute.

Notes on Syntax

While attribute binding in Aurelia is versatile and robust, there are certain syntactical nuances and limitations to be aware of to prevent unexpected behavior.

1. Expression Syntax Restrictions

   • No Chaining with ; or ,: Expressions within ${} cannot be chained using semicolons ; or commas ,. Each interpolation expression should represent a single, complete expression.

   • Restricted Primitives and Operators: Certain JavaScript primitives and operators cannot be used within interpolation expressions. These include:

     • Boolean

     • String

     • instanceof

     • typeof

     • Bitwise operators (except for the pipe | used with value converters)

   • Usage of Pipe |: The pipe character | is reserved exclusively for Aurelia's value converters within bindings and cannot be used as a bitwise operator.

2. Attribute Targeting Syntax

   The presence of both .bind and .attr syntaxes can be confusing. Here's why both exist:

   • Property vs. Attribute Binding: .bind targets the DOM property, which is suitable for standard attributes that have corresponding DOM properties. However, for custom or non-standard attributes that do not have direct property mappings, .attr is necessary to bind directly to the attribute itself.

   • Example: Binding id Using Property and Attribute

     Copy

     <!-- Property Binding -->
     <input id.bind="inputId" />
     
     <!-- Attribute Binding -->
     <input id.attr="inputId" />

     Copy

     // my-app.ts
     export class MyApp {
       inputId = 'user-input';
     }

     Result:

     • Using .bind, Aurelia binds to the id property of the input element.

     • Using .attr, Aurelia binds directly to the id attribute in the DOM.

3. Choosing Between Interpolation and Keyword Binding

   Both interpolation and keyword binding can achieve similar outcomes. The choice between them often comes down to preference and specific use case requirements.

   • Performance and Features: There is no significant performance difference between the two. Both are equally efficient and offer similar capabilities.

   • Readability and Maintainability: Interpolation can be more readable for simple string concatenations, while keyword bindings offer more explicit control for complex bindings.

Example: Using Value Converters for Formatting

Binding with a Value Converter

<!-- my-app.html -->
<span class="price">${totalPrice | currency}</span>

// my-app.ts
export class MyApp {
  totalPrice = 199.99;
}

// currency-value-converter.ts
export class CurrencyValueConverter {
  toView(value: number) {
    return `$${value.toFixed(2)}`;
  }
}

Result: Displays the totalPrice formatted as currency, e.g., "$199.99".

Summary

Attribute binding in Aurelia offers a flexible and powerful means to synchronize data between your view model and the DOM. By understanding and utilizing the various binding commands and techniques, you can create dynamic, responsive, and maintainable user interfaces. Always consider the specific needs of your project when choosing between different binding strategies, and leverage Aurelia's features to their fullest to enhance your application's interactivity and user experience.

Aurelia 2 allows you to managed variables directly within your view templates: the <let> custom element. This element allows you to declare and initialize variables inline in your HTML, making your templates more dynamic and readable. <let> is incredibly versatile, supporting a range of value assignments, from simple strings and interpolation to complex expressions and bindings to your view model. This capability significantly enhances template flexibility and reduces the need for excessive view model code for simple template-specific logic.

Declaring Template Variables with <let>

The <let> element provides a straightforward syntax for declaring variables directly within your templates. The basic structure is as follows:

• <let>: The custom element tag that signals the declaration of a template variable.

• variable-name: The name you choose for your template variable. In templates, you will reference this variable name in its camelCase form (e.g., variableName).

• "variable value": The initial value assigned to the variable. This can be a string literal, an interpolation expression, a binding expression, or any valid JavaScript expression that Aurelia can evaluate within the template context.

Basic String Assignment

You can assign simple string literals to <let> variables:

To display the value of this variable in your template, use interpolation with the camelCase version of the variable name:

This will render:

Binding Expressions for Dynamic Values

<let> variables are not limited to static strings. You can use binding expressions to assign dynamic values that are calculated or updated based on your view model or other template logic.

Example: Simple Mathematical Expression

Now, you can display the result of this calculation:

This will output:

Example: Binding to View Model Properties

You can bind a <let> variable to properties defined in your view model, making template variables reactive to changes in your data:

In this example, both ${userName} interpolations will display "John Doe". If you update the userName property in your view model, both interpolations will dynamically reflect the change.

Example: Using Template Expressions

<let> variables can also be assigned values derived from template expressions, including function calls, ternary operators, and more:

Here, isEvening will be a boolean value based on the current hour, and timeOfDayMessage will be dynamically set to either "Good evening" or "Good day" based on the value of isEvening.

Scoping of Template Variables

<let> variables are scoped to the template in which they are declared. This means a variable declared with <let> is only accessible within the template block where it's defined. This scoping helps prevent naming conflicts and keeps your templates organized and predictable.

Example: Scoped Variables in repeat.for

When using <let> within a repeat.for loop, each iteration of the loop will have its own instance of the <let> variable, ensuring that variables are correctly associated with each repeated item.

In this example, itemIndex is scoped to each <li> element within the repeat.for loop, correctly displaying the index for each item in the list.

Practical Use Cases for <let>

<let> is incredibly useful in various template scenarios. Here are a few common use cases:

1. Simplifying Complex Expressions

When you have complex expressions that are used multiple times within a template, you can use <let> to assign the result of the expression to a variable, improving readability and maintainability.

Before using <let>:

After using <let>:

Using <let subtotal.bind="quantity * price"> makes the template cleaner and easier to understand, especially if the calculation is more complex.

2. Conditional Rendering Logic

You can use <let> in conjunction with conditional attributes like if.bind or else to manage template variables based on conditions.

Here, showDetails is used to control both the button text and the visibility of the details section, simplifying the conditional logic within the template.

3. Data Transformation within Templates

You can perform simple data transformations directly within your templates using <let>, although for more complex transformations, value converters are generally recommended.

Example: Formatting a Date

This example formats the current date using toLocaleDateString() and stores it in formattedDate for display.

4. Creating Reusable Template Snippets

While not its primary purpose, <let> can indirectly contribute to creating reusable template snippets by encapsulating logic and variables within a specific section of your template. Combined with custom elements or template parts, <let> helps in modularizing your view templates.

Considerations when Using <let>

• Keep it Simple: While <let> is powerful, it's best used for template-specific variables and simple logic. For complex data manipulation or business logic, keep that in your view model.

• Readability: Use descriptive variable names for <let> to maintain template readability.

• Scoping: Be mindful of the scope of <let> variables. They are limited to the template in which they are declared.

• Alternatives: For complex data transformations or reusable formatting logic, consider using Aurelia's value converters, which are designed for these purposes and promote better separation of concerns.

By design, Aurelia templates limit direct access to global variables like window or document for security and maintainability reasons. However, Aurelia recognizes that some JavaScript globals are frequently needed—like Math, JSON, or Array—and therefore provides a predefined list of global objects that can be safely accessed in template expressions.

Why Limit Global Access?

• Security: Restricting direct access to browser globals reduces the risk of accidental or malicious operations on sensitive objects.

• Maintainability: Encourages developers to keep logic in their view models, improving code clarity.

• Performance: Minimizes the amount of unnecessary logic in templates, preventing overuse of global operations in tight rendering loops.

Despite these constraints, Aurelia acknowledges the utility of common global constructors and functions. Below is the canonical list accessible within Aurelia 2 templates without additional configuration:

• Infinity

• NaN

• isFinite

• isNaN

• parseFloat

• parseInt

• decodeURI

• decodeURIComponent

• encodeURI

• encodeURIComponent

• Array

• BigInt

• Boolean

• Date

• Map

• Number

• Object

• RegExp

• Set

• String

• JSON

• Math

• Intl

Example Usages of Built-In Globals

Below are illustrative examples showing how to use these built-in globals in Aurelia templates. The syntax is identical to standard JavaScript, but you simply call them within Aurelia’s binding expressions.

1. Working with JSON

Serialize an object for debugging or quick display:

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

2. Mathematical Operations with Math

Perform simple or complex calculations:

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

3. Conditional Rendering with isNaN

Use global numeric checks to conditionally display elements:

<template>
  <input type="text" value.bind="value" />
  <p if.bind="isNaN(value)">This is not a valid number!</p>
</template>

4. Regular Expressions with RegExp

Construct inline regular expressions for quick validation:

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

5. Dynamic Property Access with Object

Use Object methods for reflection or retrieval:

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

6. Set Operations with Set

De-duplicate arrays or combine sets inline:

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

7. Encoding & Decoding URLs

Leverage encodeURI / decodeURI for safe link construction:

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

8. Number Formatting with Intl.NumberFormat

Localize numbers, currency, or dates easily:

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

9. Complex Array Manipulations

Filter, map, and transform arrays:

<template>
  <p>Active Items: ${Array.from(dataSet).filter(i => i.active).map(i => i.name).join(', ')}</p>
</template>

Best Practices and Considerations

1. Use Sparingly

   • Keep business logic in your view models, not in templates. Inline calls to complex global functions (e.g., JSON.stringify on large data) can degrade performance and reduce readability.

2. Security

   • Even though Aurelia limits global access, treat any data you process via global functions (e.g., decodeURI) with caution to prevent potential XSS attacks or other vulnerabilities.

3. Performance

   • Template expressions run on each re-render. If you repeatedly perform expensive operations (like JSON.stringify on large objects), consider handling them in the view model and binding to a computed property instead.

4. Reactivity

   • Accessing global objects doesn’t magically become reactive. If you want to update the UI when data changes, store and manipulate it in the view model, ensuring Aurelia’s change detection can pick it up.

5. Clarity and Testing

   • Test heavy logic in a view model or service, not in templates. This approach keeps your code testable with unit tests and fosters a separation of concerns.

By sticking to these guidelines, you can leverage Aurelia’s built-in global access without sacrificing maintainability or performance.

Event binding in Aurelia 2 offers a streamlined approach to managing DOM events directly within your templates. By declaratively attaching event listeners in your view templates, you can effortlessly respond to user interactions like clicks, keystrokes, form submissions, and more. This guide explores the intricacies of event binding in Aurelia 2, providing detailed explanations and practical examples to deepen your understanding and effective utilization of this feature.

Understanding Event Binding

Aurelia 2 simplifies the connection between DOM events and your view model methods. It employs a clear and concise syntax, enabling you to specify the event type and the corresponding method to be invoked in your view model when that event occurs.

Event Binding Syntax

The general syntax for event binding in Aurelia 2 follows this pattern:

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

• <element>: The HTML element to which you are attaching the event listener.

• event: The name of the DOM event you wish to listen for (e.g., click, input, mouseover).

• .command: The binding command that instructs Aurelia how to handle the event. Common commands are .trigger and .capture.

• methodName: The name of the method in your view model that will be executed when the event is dispatched.

• argument1, argument2, ...: Optional arguments that you can pass to the methodName.

Event Binding Commands: .trigger and .capture

Aurelia 2 primarily offers two commands for event binding, each controlling the event listening phase:

1. .trigger: This command attaches an event listener that reacts to events during the bubbling phase. This is the most frequently used and generally recommended command for event binding as it aligns with typical event handling patterns in web applications. Events are first captured by the deepest element and then propagate upwards through the DOM tree.

2. .capture: This command listens for events during the capturing phase. Capturing is the less common phase where events propagate downwards from the window to the target element. .capture is typically used in specific scenarios, such as when you need to intercept an event before it reaches child elements, potentially preventing default behaviors or further propagation.

Example: Click Event Binding using .trigger

To bind a click event on a button to a method named handleClick in your view model, you would use:

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

When a user clicks the "Click Me" button, Aurelia will execute the handleClick method defined in your associated view model.

Passing Event Data to Handlers

Often, you need access to the event object or want to pass additional data to your event handler method. Aurelia provides a straightforward way to do this.

To pass the DOM event object itself to your handler, use the $event special variable:

<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: MouseEvent) {
    console.log('Button clicked!', event);
    // Access event properties like event.target, event.clientX, etc.
  }
}

You can also pass custom arguments along with the event:

<button click.trigger="removeItem(item.id, $event)">Remove Item</button>

export class MyViewModel {
  removeItem(itemId: number, event: MouseEvent) {
    console.log(`Removing item with ID: ${itemId}`, event);
    // Logic to remove the item
  }
}

Common DOM Events

Aurelia 2 supports binding to all standard DOM events. Here are some frequently used events in web development:

click

The click event is triggered when a pointing device button (typically a mouse button) is both pressed and released while the pointer is inside the element. It is commonly used for buttons, links, and interactive elements.

<button click.trigger="submitForm()">Submit</button>
<a href="#" click.trigger="openModal()">Learn More</a>

input

The input event fires when the value of an <input>, <textarea>, or <select> element has been changed. It's useful for real-time validation or dynamic updates based on user input.

<input type="text" input.trigger="updateSearchQuery($event.target.value)" placeholder="Search..." />

change

The change event is fired when the value of an element has been changed and the element loses focus. This is often used for <input>, <select>, and <textarea> elements when you want to react after the user has finished making changes.

<select change.trigger="selectTheme($event.target.value)">
  <option value="light">Light Theme</option>
  <option value="dark">Dark Theme</option>
</select>

mouseover and mouseout

The mouseover event occurs when the mouse pointer is moved onto an element, and mouseout occurs when it is moved off of an element. These are useful for hover effects and interactive UI elements.

<div mouseover.trigger="highlight()" mouseout.trigger="unhighlight()">Hover Me</div>

keydown, keyup, and keypress

These keyboard events are triggered when a key is pressed down, released, or pressed and released, respectively. keydown and keyup are generally preferred for capturing special keys like arrows, Ctrl, Shift, etc., while keypress is more suited for character input.

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

Controlling Event Propagation

In DOM event handling, events can "bubble" up the DOM tree (from the target element up to the document) or "capture" down (from the document to the target element). Sometimes you need to control this propagation. Within your event handler methods, you can use methods of the event object to manage propagation:

• event.stopPropagation(): Prevents the event from further bubbling up the DOM tree to parent elements.

• event.preventDefault(): Prevents the default action associated with the event (if it's cancelable), without stopping event propagation. For example, preventDefault on a click event of a link (<a>) would stop the browser from navigating to the link's href.

Advanced Event Binding Techniques

Aurelia 2 provides capabilities beyond basic event binding, allowing for performance optimization and handling specific scenarios.

Throttling and Debouncing Event Handlers

For events that fire rapidly and repeatedly, such as mousemove, scroll, or input, calling an event handler function on every event can be performance-intensive. Aurelia's binding behaviors offer throttle and debounce to limit the rate at which your handler is invoked.

Throttling: Ensures a function is called at most once in a specified time interval.

<div mousemove.trigger="trackMouse($event) & throttle:50">Move mouse here</div>

In this example, trackMouse will be executed at most every 50 milliseconds, even if mousemove events are firing more frequently.

Debouncing: Delays the execution of a function until after a certain amount of time has passed since the last time the event was triggered. Useful for autocomplete or search features to avoid making API calls on every keystroke.

<input type="text" input.trigger="searchQuery($event.target.value) & debounce:300" placeholder="Search" />

Here, searchQuery will be called 300ms after the user stops typing, reducing the number of search requests.

Custom Events

Aurelia 2 fully supports custom events, which are essential when working with custom elements or integrating third-party libraries that dispatch their own events.

<my-custom-element data-loaded.trigger="handleDataLoaded($event)"></my-custom-element>

In this scenario, data-loaded is a custom event emitted by <my-custom-element>. handleDataLoaded in the parent view model will be invoked when this custom event is dispatched.

Event Binding Examples and Use Cases

To solidify your understanding, let's explore practical examples showcasing different event binding scenarios in Aurelia 2.

Self-Delegating Events with .self

The self binding behavior ensures that an event handler is only triggered if the event originated directly from the element to which the listener is attached, and not from any of its child elements (due to event bubbling).

<div click.trigger="divClicked() & self">
  <p>Clicking here will trigger divClicked</p>
  <button click.trigger="buttonClicked()">Clicking button will NOT trigger divClicked</button>
</div>

In this setup, divClicked() will only be executed if the click originates directly on the <div> element. Clicks on the <button> (a child element) will trigger buttonClicked() but will not bubble up to trigger divClicked() due to the & self behavior.

Checkbox change Event and Two-Way Binding

Combine event binding with two-way binding for interactive form elements like checkboxes.

<input type="checkbox" checked.bind="isAgreed" change.trigger="agreementChanged()" id="agreementCheckbox">
<label for="agreementCheckbox">I agree to the terms</label>

export class MyViewModel {
  isAgreed = false;

  agreementChanged() {
    console.log('Agreement status changed:', this.isAgreed);
    // Perform actions based on checkbox state
  }
}

Here, checked.bind="isAgreed" keeps the isAgreed property in sync with the checkbox state (two-way binding). change.trigger="agreementChanged()" additionally allows you to execute custom logic when the checkbox state changes.

Handling Keyboard Events for Specific Keys

React to specific key presses within input fields.

<input type="text" keydown.trigger="handleKeyDown($event)" placeholder="Type here">

export class MyViewModel {
  handleKeyDown(event: KeyboardEvent) {
    if (event.key === 'Enter') {
      console.log('Enter key pressed!');
      // Perform action on Enter key press (e.g., submit form)
      event.preventDefault(); // Prevent default form submission if inside a form
    } else if (event.key === 'Escape') {
      console.log('Escape key pressed!');
      // Handle Escape key press (e.g., clear input)
    }
    // ... handle other keys as needed
  }
}

This example shows how to check event.key to handle specific keys like "Enter" and "Escape".

Event Delegation for Dynamic Lists

Efficiently handle events on dynamically generated lists using event delegation. Attach a single event listener to the parent <ul> or <div> instead of individual listeners to each list item.

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

export class MyViewModel {
  items = [{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }];

  listItemClicked(event: Event) {
    const target = event.target as HTMLElement;
    if (target.tagName === 'LI') {
      const itemId = target.dataset.itemId;
      console.log(`List item clicked, ID: ${itemId}`);
      // Logic to handle click on list item with ID itemId
    }
  }
}

The listItemClicked handler attached to the <ul> will be triggered for clicks on any <li> within it due to event bubbling. We check event.target to ensure the click originated from an <li> and extract the data-item-id.

Custom Event Communication Between Components

Parent components can listen for and react to custom events dispatched by child custom elements.

Custom Element (Child):

import { bindable, customElement, Element } from 'aurelia';
import { inject } from '@aurelia/kernel';

@customElement({ name: 'my-button', template: `<button click.trigger="handleClick()">\${label}</button>` })
@inject(Element)
export class MyButton {
  @bindable label = 'Click Me';
  constructor(private element: Element) {}

  handleClick() {
    this.element.dispatchEvent(new CustomEvent('button-clicked', {
      bubbles: true, // Allow event to bubble up
      detail: { message: 'Button with label "' + this.label + '" was clicked' }
    }));
  }
}

Parent Component (Parent):

<my-button label="Action Button" button-clicked.trigger="handleButtonClick($event)"></my-button>

export class ParentViewModel {
  handleButtonClick(event: CustomEvent) {
    console.log('Custom event "button-clicked" received:', event.detail.message);
    // Handle the custom event
  }
}

When the button in <my-button> is clicked, it dispatches a custom event button-clicked. The parent component listens for this event using button-clicked.trigger and executes handleButtonClick, receiving event details in $event.detail.

Autocomplete with Debounced Input

Implement autocomplete functionality with debouncing to reduce API calls during typing.

<input type="text" input.trigger="autocomplete($event.target.value) & debounce:500" placeholder="Start typing..." />
<ul if.bind="suggestions.length">
  <li repeat.for="suggestion of suggestions">${suggestion}</li>
</ul>

export class MyViewModel {
  searchQuery = '';
  suggestions = [];

  autocomplete(query: string) {
    this.searchQuery = query;
    if (query.length > 2) {
      // Simulate API call for suggestions (replace with actual API call)
      setTimeout(() => {
        this.suggestions = [`${query} suggestion 1`, `${query} suggestion 2`, `${query} suggestion 3`];
      }, 300);
    } else {
      this.suggestions = [];
    }
  }
}

The autocomplete method will be called 500ms after the last input event. This delay allows users to finish typing before triggering the (simulated) autocomplete API call, improving performance.

Event Modifiers: Enhancing Event Handling

Event modifiers provide a declarative way to apply conditions or actions to event bindings directly in your templates. Event modifiers are appended to the event name after a colon:

<element event.trigger[:modifier]="methodName()">

Aurelia provides built-in modifiers for common event handling scenarios, and you can extend them with custom mappings.

Mouse and Keyboard Event Modifiers

Aurelia has built-in support for modifiers related to mouse buttons and keyboard keys.

Example: ctrl Key Modifier

Execute onCtrlClick() only when the button is clicked and the Ctrl key is pressed.

<button click.trigger:ctrl="onCtrlClick()">Ctrl + Click</button>

Example: ctrl+enter Key Combination

Execute send() only when the Enter key is pressed while the Ctrl key is also held down. Modifiers can be combined using +.

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

prevent and stop Modifiers

Declaratively call event.preventDefault() and event.stopPropagation() using modifiers.

Example: prevent and stop Modifiers

Call validate() when the button is clicked, and also prevent the default button behavior and stop event propagation.

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

Mouse Button Modifiers: left, middle, right

Handle clicks based on specific mouse buttons.

Example: middle Mouse Button Modifier

Execute newTab() only when the button is clicked with the middle mouse button.

<button click.trigger:middle="newTab()">Open in New Tab (Middle Click)</button>

Keyboard Key Mappings and Custom Modifiers

You can use character codes as modifiers for keyboard events. For example, 75 is the char code for uppercase 'K'.

Example: Ctrl + K using Char Code Modifier

Execute openSearchDialog() when Ctrl + K is pressed in the textarea.

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

While using char codes works, it can be less readable. You can create custom key mappings to use more descriptive modifier names. For example, map upper_k to the key code for 'K'.

Custom Key Mapping Setup (in your main application file, e.g., main.ts):

import Aurelia, { AppTask, IKeyMapping } from 'aurelia';

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

Now you can use :upper_k as a modifier:

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

This makes your template more readable as :ctrl+upper_k is more self-explanatory than :ctrl+75.

Conclusion

Event binding in Aurelia 2 is a powerful and intuitive mechanism for creating interactive web applications. By mastering the syntax, commands, event modifiers, and advanced techniques like throttling and custom events, you can effectively handle user interactions and build dynamic, responsive user interfaces. Leverage the .trigger command for typical scenarios and .capture when you need to intercept events during the capturing phase. With these tools and patterns, you can craft a seamless and engaging user experience in your Aurelia 2 applications.

Custom attributes in Aurelia empower you to extend and decorate standard HTML elements by embedding custom behavior and presentation logic. They allow you to wrap or integrate existing HTML plugins and libraries, or simply enhance your UI components with additional dynamic functionality. This guide provides a comprehensive overview—from basic usage to advanced techniques—to help you leverage custom attributes effectively in your Aurelia 2 projects.

Table of Contents

1. Introduction

2. Creating a Basic Custom Attribute

3. Explicit Custom Attributes

   • Explicit Attribute Naming

   • Attribute Aliases

4. Single Value Binding

5. Bindable Properties and Change Detection

6. Options Binding for Multiple Properties

7. Specifying a Primary Bindable Property

8. Accessing the Host Element

9. Finding Related Custom Attributes

10. Lifecycle Hooks and Best Practices

11. Integrating Third-Party Libraries

Introduction

Custom attributes are one of the core building blocks in Aurelia 2. Similar to components, they encapsulate behavior and style, but are applied as attributes to existing DOM elements. This makes them especially useful for:

• Decorating elements with additional styling or behavior.

• Wrapping third-party libraries that expect to control their own DOM structure.

• Creating reusable logic that enhances multiple elements across your application.

Creating a Basic Custom Attribute

At its simplest, a custom attribute is defined as a class that enhances an element. Consider this minimal example:

export class CustomPropertyCustomAttribute {
  // Custom logic can be added here
}

When you apply a similar pattern using CustomElement instead, you are defining a component. Custom attributes are a more primitive (yet powerful) way to extend behavior without wrapping the entire element in a component.

Example: Red Square Attribute

This custom attribute adds a fixed size and a red background to any element it is applied to:

import { INode, resolve } from 'aurelia';

export class RedSquareCustomAttribute {
  private element: HTMLElement = resolve(INode) as HTMLElement;

  constructor() {
    // Set fixed dimensions and a red background on initialization
    this.element.style.width = this.element.style.height = '100px';
    this.element.style.backgroundColor = 'red';
  }
}

Usage in HTML:

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

<div red-square></div>

The <import> tag ensures that Aurelia’s dependency injection is aware of your custom attribute. When applied, the <div> will render with the specified styles.

Explicit Custom Attributes

To gain finer control over your attribute’s name and configuration, Aurelia provides the @customAttribute decorator. This lets you explicitly define the attribute name and even set up aliases.

Explicit Attribute Naming

By default, the class name might be used to infer the attribute name. However, you can explicitly set a custom name:

import { customAttribute, INode, resolve } from 'aurelia';

@customAttribute({ name: 'red-square' })
export class RedSquare {
  private element: HTMLElement = resolve(INode) as HTMLElement;

  constructor() {
    this.element.style.width = this.element.style.height = '100px';
    this.element.style.backgroundColor = 'red';
  }
}

Attribute Aliases

You can define one or more aliases for your custom attribute. This allows consumers of your attribute flexibility in naming:

import { customAttribute, INode, resolve } from 'aurelia';

@customAttribute({ name: 'red-square', aliases: ['redify', 'redbox'] })
export class RedSquare {
  private element: HTMLElement = resolve(INode) as HTMLElement;

  constructor() {
    this.element.style.width = this.element.style.height = '100px';
    this.element.style.backgroundColor = 'red';
  }
}

Now the attribute can be used interchangeably using any of the registered names:

<div red-square></div>
<div redify></div>
<div redbox></div>

Single Value Binding

For simple cases, you might want to pass a single value to your custom attribute without explicitly declaring a bindable property. Aurelia will automatically populate the value property if a value is provided.

import { INode, resolve } from 'aurelia';

export class RedSquareCustomAttribute {
  private element: HTMLElement = resolve(INode) as HTMLElement;
  private value: string;

  constructor() {
    this.element.style.width = this.element.style.height = '100px';
    // Use a default color, but override it if a value is supplied during binding.
    this.element.style.backgroundColor = 'red';
  }

  bind() {
    if (this.value) {
      this.element.style.backgroundColor = this.value;
    }
  }
}

To further handle changes in the value over time, you can define the property as bindable:

import { bindable, INode, resolve } from 'aurelia';

export class RedSquareCustomAttribute {
  private element: HTMLElement = resolve(INode) as HTMLElement;

  @bindable() private value: string;

  constructor() {
    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;
  }
}

Bindable Properties and Change Detection

Custom attributes often need to be configurable. Using the @bindable decorator, you can allow users to pass in parameters that change the behavior or style dynamically. In the following example, the background color is configurable:

import { bindable, INode, resolve } from 'aurelia';

export class ColorSquareCustomAttribute {
  @bindable() color: string = 'red';

  constructor(private element: HTMLElement = resolve(INode)) {
    this.element.style.width = this.element.style.height = '100px';
    this.element.style.backgroundColor = this.color;
  }

  bound() {
    // Ensure the element reflects the current color after binding
    this.element.style.backgroundColor = this.color;
  }

  colorChanged(newColor: string, oldColor: string) {
    // Update the background color dynamically when the property changes
    this.element.style.backgroundColor = newColor;
  }
}

You can extend this to support multiple bindable properties. For example, to also allow a dynamic size:

import { bindable, INode, resolve } from 'aurelia';

export class ColorSquareCustomAttribute {
  @bindable() color: string = 'red';
  @bindable() size: string = '100px';

  constructor(private element: HTMLElement = resolve(INode)) {
    this.applyStyles();
  }

  bound() {
    this.applyStyles();
  }

  colorChanged(newColor: string) {
    this.element.style.backgroundColor = newColor;
  }

  sizeChanged(newSize: string) {
    this.element.style.width = this.element.style.height = newSize;
  }

  private applyStyles() {
    this.element.style.width = this.element.style.height = this.size;
    this.element.style.backgroundColor = this.color;
  }
}

Options Binding for Multiple Properties

When you have more than one bindable property, you can use options binding syntax to bind multiple properties at once. Each bindable property in the view model corresponds to a dash-case attribute in the DOM. For instance:

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

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

The Aurelia binding engine converts the attribute names (e.g., color-square) to the corresponding properties in your class.

Specifying a Primary Bindable Property

If one of your bindable properties is expected to be used more frequently, you can mark it as the primary property. This simplifies the syntax when binding:

import { bindable, INode, resolve } from 'aurelia';

export class ColorSquareCustomAttribute {
  @bindable({ primary: true }) color: string = 'red';
  @bindable() size: string = '100px';

  private element: HTMLElement = resolve(INode) as HTMLElement;

  constructor() {
    this.applyStyles();
  }

  bound() {
    this.applyStyles();
  }

  colorChanged(newColor: string) {
    this.element.style.backgroundColor = newColor;
  }

  sizeChanged(newSize: string) {
    this.element.style.width = this.element.style.height = newSize;
  }

  private applyStyles() {
    this.element.style.width = this.element.style.height = this.size;
    this.element.style.backgroundColor = this.color;
  }
}

With a primary property defined, you can bind directly:

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

<!-- Using a literal value -->
<div color-square="blue"></div>

<!-- Or binding the value dynamically -->
<div color-square.bind="myColour"></div>

Accessing the Host Element

A key aspect of custom attributes is that they work directly on DOM elements. To manipulate these elements (e.g., updating styles or initializing plugins), you need to access the host element. Aurelia provides a safe way to do this using dependency injection with INode.

import { INode, resolve } from 'aurelia';

export class RedSquareCustomAttribute {
  // Resolve the host element safely, even in Node.js environments
  private element: HTMLElement = resolve(INode) as HTMLElement;

  constructor() {
    // Now you can modify the host element directly
    this.element.style.width = this.element.style.height = '100px';
    this.element.style.backgroundColor = 'red';
  }
}

Note: While you can also use resolve(Element) or resolve(HTMLElement), using INode is safer in environments where global DOM constructors might not be available (such as Node.js).

Finding Related Custom Attributes

In complex UIs, you might have multiple custom attributes working together (for example, a dropdown with associated toggle buttons). Aurelia offers the CustomAttribute.closest function to traverse the DOM and locate a related custom attribute. This function can search by attribute name or by constructor.

Example: Searching by Attribute Name

<div foo="1">
  <div bar="2"></div>
</div>

import { CustomAttribute, resolve, INode, customAttribute } from 'aurelia';

@customAttribute('bar')
export class Bar {
  host: HTMLElement = resolve(INode) as HTMLElement;
  // Find the closest ancestor that has the 'foo' custom attribute
  parent = CustomAttribute.closest(this.host, 'foo');
}

Example: Searching by Constructor

If you want to search based on the attribute’s constructor (for stronger typing), you can do so:

import { CustomAttribute, resolve, INode, customAttribute } from 'aurelia';
import { Foo } from './foo';

@customAttribute('bar')
export class Bar {
  host: HTMLElement = resolve(INode) as HTMLElement;
  // Find the closest ancestor that is an instance of the Foo custom attribute
  parent = CustomAttribute.closest(this.host, Foo);
}

Lifecycle Hooks and Best Practices

Custom attributes, like components, have lifecycle hooks that let you run code at different stages of their existence:

• bind() / unbind(): Initialize or clean up data bindings.

• attached() / detached(): Perform actions when the host element is attached to or removed from the DOM.

Example: Using Lifecycle Hooks

import { bindable, INode, resolve, customAttribute } from 'aurelia';

@customAttribute({ name: 'dynamic-style' })
export class DynamicStyleCustomAttribute {
  @bindable() color: string = 'red';
  @bindable() size: string = '100px';
  private element: HTMLElement = resolve(INode) as HTMLElement;

  bind() {
    // Initial setup or computation can go here
    this.applyStyles();
  }

  attached() {
    // For DOM-dependent initialization, e.g., third-party plugin initialization
  }

  colorChanged(newColor: string) {
    this.element.style.backgroundColor = newColor;
  }

  sizeChanged(newSize: string) {
    this.element.style.width = this.element.style.height = newSize;
  }

  private applyStyles() {
    this.element.style.width = this.element.style.height = this.size;
    this.element.style.backgroundColor = this.color;
  }

  detached() {
    // Clean up event listeners or other resources if needed
  }

  unbind() {
    // Clean up any remaining state
  }
}

Best Practices:

• Separation of Concerns: Keep your custom attribute logic focused on enhancing the host element, and avoid heavy business logic.

• Performance: Minimize DOM manipulations inside change handlers. If multiple properties change at once, consider batching style updates.

• Testing: Write unit tests for your custom attributes to ensure that lifecycle hooks and bindings work as expected.

• Documentation: Comment your code and document the expected behavior of your custom attributes, especially if you provide aliases or multiple bindable properties.

Integrating Third-Party Libraries

Often, you’ll want to incorporate functionality from third-party libraries—such as sliders, date pickers, or custom UI components—into your Aurelia applications. Custom attributes provide an excellent way to encapsulate the integration logic, ensuring that the third-party library initializes, updates, and cleans up properly within Aurelia's lifecycle.

When to Use Custom Attributes for Integration

• DOM Manipulation: Many libraries require direct access to the DOM element for initialization.

• Lifecycle Management: You can leverage Aurelia's lifecycle hooks (attached() and detached()) to manage resource allocation and cleanup.

• Dynamic Updates: With bindable properties, you can pass configuration options to the library and update it reactively when those options change.

Example: Integrating a Hypothetical Slider Library

Consider a third-party slider library called AwesomeSlider that initializes a slider on a given DOM element. Below is an example of how to wrap it in a custom attribute.

import { customAttribute, bindable, INode, resolve } from 'aurelia';
// Import the third-party slider library (this is a hypothetical example)
import AwesomeSlider from 'awesome-slider';

@customAttribute('awesome-slider')
export class AwesomeSliderCustomAttribute {
  // Allow dynamic options to be bound from the view
  @bindable() options: any = {};

  // The instance of the third-party slider
  private sliderInstance: any;

  // Safely resolve the host element
  private element: HTMLElement = resolve(INode) as HTMLElement;

  attached() {
    // Initialize the slider when the element is attached to the DOM.
    // This ensures that the DOM is ready for manipulation.
    try {
      this.sliderInstance = new AwesomeSlider(this.element, this.options);
    } catch (error) {
      console.error('Failed to initialize AwesomeSlider:', error);
    }
  }

  optionsChanged(newOptions: any, oldOptions: any) {
    // Update the slider if its configuration changes at runtime.
    // This callback is triggered when the bound `options` property changes.
    if (this.sliderInstance && typeof this.sliderInstance.updateOptions === 'function') {
      this.sliderInstance.updateOptions(newOptions);
    }
  }

  detached() {
    // Clean up the slider instance when the element is removed from the DOM.
    // This prevents memory leaks and removes event listeners.
    if (this.sliderInstance && typeof this.sliderInstance.destroy === 'function') {
      this.sliderInstance.destroy();
    }
  }
}

In place of our hypothetical AwesomeSlider library, you can use any third-party library that requires DOM manipulation such as jQuery plugins, D3.js, or even custom UI components.

Template references in Aurelia 2 offer a powerful and declarative mechanism to establish direct links between elements in your HTML templates and properties in your JavaScript or TypeScript view models. Using the ref attribute, you can easily obtain references to specific DOM elements, custom element instances, custom attribute instances, or even Aurelia controllers, enabling efficient DOM manipulation and streamlined interaction with template elements.

Declaring Template References

Basic Usage: Referencing DOM Elements

To create a template reference to a standard HTML element, simply add the ref attribute to the element within your template. The value assigned to ref will be the name of the property in your view model that will hold the reference.

<input type="text" ref="firstNameInput" placeholder="First name">

In this basic example, firstNameInput is declared as a template reference. Aurelia will automatically populate a property in your view model with the same name, making the <input> element directly accessible.

Accessing References in Templates

Template references become immediately available for use within the template itself. You can directly access properties and methods of the referenced element using the reference name.

For example, to dynamically display the current value of the firstNameInput field:

<p>You are typing: "${firstNameInput.value}"</p>

As the user types in the input field, the <p> element will update in real-time, displaying the current value accessed through firstNameInput.value.

Accessing References in View Models

To access a template reference in your view model, you need to declare a property in your view model class that matches the reference name you used in the template. For TypeScript projects, it's strongly recommended to explicitly type this property for enhanced type safety and code maintainability.

import { customElement } from 'aurelia';

@customElement({ name: 'my-app', template: `<input type="text" ref="firstNameInput" placeholder="First name">` })
export class MyApp {
  firstNameInput: HTMLInputElement; // Explicitly typed template reference

  bound() {
    // 'firstNameInput' is now available after the view is bound
    console.log('Input element reference:', this.firstNameInput);
  }

  focusInput() {
    if (this.firstNameInput) {
      this.firstNameInput.focus(); // Programmatically focus the input element
    }
  }
}

Important Notes:

• Property Naming: The property name in your view model must exactly match the value of the ref attribute in your template (firstNameInput in the example above).

• Type Safety: In TypeScript, always declare the type of your template reference property (e.g., HTMLInputElement, HTMLDivElement, MyCustomElement). This improves code readability and helps catch type-related errors early.

• Lifecycle Timing: Template references are not available during the view model's constructor. They become available after the view is bound to the view model, typically in lifecycle hooks like bound() or later.

Advanced Usage: Referencing Components and Controllers

Aurelia's ref attribute extends beyond simple DOM elements. It provides powerful options to reference component instances and controllers of custom elements and attributes.

1. component.ref: Referencing Custom Element Instances (View Models)

To obtain a reference to the view model instance of a custom element, use component.ref="expression". This was previously known as view-model.ref in Aurelia v1.

<my-custom-element component.ref="customElementViewModel"></my-custom-element>

In your view model:

import { customElement } from 'aurelia';
import { MyCustomElement } from './my-custom-element'; // Assuming MyCustomElement is defined elsewhere

@customElement({ name: 'app', template: `<my-custom-element component.ref="customElementViewModel"></my-custom-element>` })
export class App {
  customElementViewModel: MyCustomElement; // Typed reference to the custom element's view model

  interactWithCustomElement() {
    if (this.customElementViewModel) {
      this.customElementViewModel.someMethodOnViewModel(); // Call a method on the custom element's view model
    }
  }
}

component.ref is invaluable when you need to directly interact with the logic and data encapsulated within a custom element's view model from a parent component.

2. custom-attribute.ref: Referencing Custom Attribute Instances (View Models)

Similarly, to reference the view model instance of a custom attribute applied to an element, use custom-attribute.ref="expression".

<div my-custom-attribute custom-attribute.ref="customAttributeViewModel"></div>

In your view model:

import { customElement } from 'aurelia';
import { MyCustomAttribute } from './my-custom-attribute'; // Assuming MyCustomAttribute is defined elsewhere

@customElement({ name: 'app', template: `<div my-custom-attribute custom-attribute.ref="customAttributeViewModel"></div>` })
export class App {
  customAttributeViewModel: MyCustomAttribute; // Typed reference to the custom attribute's view model

  useCustomAttribute() {
    if (this.customAttributeViewModel) {
      this.customAttributeViewModel.doSomethingWithAttribute(); // Call a method on the custom attribute's view model
    }
  }
}

custom-attribute.ref is useful when you need to interact with the behavior or state managed by a custom attribute from the surrounding view model.

3. controller.ref: Referencing Aurelia Controller Instances (Advanced)

For more advanced scenarios, controller.ref="expression" allows you to access the Aurelia Controller instance of a custom element. The Controller provides access to Aurelia's internal workings and lifecycle management for the element. This is less commonly needed but can be powerful for framework-level integrations or very specific use cases.

<my-custom-element controller.ref="customElementController"></my-custom-element>

In your view model:

import { customElement, Controller } from 'aurelia';

@customElement({ name: 'app', template: `<my-custom-element controller.ref="customElementController"></my-custom-element>` })
export class App {
  customElementController: Controller; // Typed reference to the custom element's Controller

  accessControllerDetails() {
    if (this.customElementController) {
      console.log('Custom Element Controller:', this.customElementController);
      // You can access lifecycle state, bindings, etc. through the controller
    }
  }
}

controller.ref provides access to the Aurelia Controller, which is an advanced API and typically used for framework extension or very specific control over component lifecycle and binding. For most application development, component.ref or direct DOM element references are sufficient.

Practical Applications and Benefits

Template references significantly enhance Aurelia development by providing a clean, framework-integrated way to interact with elements and components. They offer several key advantages:

• Direct DOM Manipulation: Template references provide a structured and type-safe way to obtain direct references to DOM elements, which is essential for tasks like:

  • Focusing input fields programmatically (elementRef.focus()).

  • Imperative DOM manipulation when integrating with third-party libraries that require direct element access (e.g., initializing jQuery plugins, interacting with canvas elements, etc.).

  • Fine-grained control over element properties and attributes.

• Component Interaction: component.ref and custom-attribute.ref enable seamless communication and interaction between parent components and their children (custom elements and attributes). This allows for:

  • Calling methods on child component view models.

  • Accessing data and state within child components.

  • Building more complex and encapsulated component structures.

• Simplified DOM Access: Template references eliminate the need for manual DOM queries using document.querySelector or similar methods within your view models. This leads to:

  • Cleaner and more readable view model code.

  • Reduced risk of brittle selectors that break if the template structure changes.

  • Improved maintainability and refactoring capabilities.

• Integration with Third-Party Libraries: Many JavaScript libraries require direct DOM element references for initialization or interaction. Template references provide the ideal mechanism to obtain these references within an Aurelia application without resorting to less maintainable DOM query approaches.

Aurelia’s templating system offers a robust way to work with collections—be they arrays, sets, maps, or even ranges. The repeat.for binding provides a declarative approach to iterating over data, creating scopes for each iteration, and optimizing DOM updates. This guide explains the intricacies of list rendering in detail.

The repeat.for Binding

At its core, repeat.for acts like a template-based for...of loop. It iterates over a collection and creates a new rendering context for each item. For example:

<ul>
  <li repeat.for="item of items">
    ${item.name}
  </li>
</ul>

This snippet tells Aurelia to:

• Loop over each element in the items collection.

• Assign the current element to a local variable named item.

• Render the element (here, displaying item.name) for each iteration.

JavaScript Analogy:

for (let item of items) {
  console.log(item.name);
}

Keyed Iteration for Efficient DOM Updates

When working with dynamic collections, it’s crucial to minimize unnecessary DOM operations. Aurelia allows you to specify a unique key for each item in the collection. This key helps the framework:

• Track Changes: By comparing key values, Aurelia can identify which items have been added, removed, or reordered.

• Optimize Updates: Only the modified elements are updated, preserving performance.

• Maintain State: DOM elements (e.g., with user input or focus) retain their state even if their order changes.

Syntax Examples

You can declare the key using either literal or binding syntax:

<!-- Literal syntax -->
<ul>
  <li repeat.for="item of items; key: id">
    ${item.name}
  </li>
</ul>

<!-- Bound syntax -->
<ul>
  <li repeat.for="item of items; key.bind: item.id">
    ${item.name}
  </li>
</ul>

Guidelines for Keys:

• Uniqueness: Use a property that uniquely identifies each item (like an id).

• Stability: Avoid using array indices if the collection order can change.

Contextual Properties in Repeats

Inside a repeat.for block, Aurelia exposes several contextual properties that give you more control over the rendering logic:

• $index: The zero-based index of the current iteration.

• $first: A boolean that is true on the first iteration.

• $last: A boolean that is true on the final iteration.

• $even / $odd: Flags indicating whether the current index is even or odd, which is useful for styling alternating rows.

• $length: The total number of items in the collection.

• $parent: A reference to the parent binding context. This is especially useful in nested repeaters.

Example Usage

<ul>
  <li repeat.for="item of items">
    Index: ${$index} — Name: ${item.name} <br>
    Is first? ${$first} | Is last? ${$last} <br>
    Even? ${$even} | Odd? ${$odd} <br>
    Total items: ${$length}
  </li>
</ul>

For nested repeats, you can access the outer scope with $parent:

<ul>
  <li repeat.for="item of items">
    Outer index: ${$parent.$index}
  </li>
</ul>

Working with Arrays

Arrays are the most common data source for repeats. Here’s an example component and its template:

Component (my-component.ts):

export class MyComponent {
  items = [
    { name: 'John' },
    { name: 'Bill' }
  ];
}

Template (my-component.html):

<ul>
  <li repeat.for="item of items">
    ${item.name}
  </li>
</ul>

Note: Aurelia tracks changes in arrays when you use array methods like push, pop, or splice. Direct assignments (e.g., array[index] = value) won’t trigger change detection.

Generating Ranges

repeat.for isn’t limited to collections—it can also generate a sequence of numbers. For instance, to create a countdown:

<p repeat.for="i of 10">
  ${10 - i}
</p>
<p>Blast Off!</p>

This iterates 10 times and computes 10 - i on each pass.

Iterating Sets

Sets are handled much like arrays. The syntax remains the same, though the underlying collection is a Set.

Component (repeater-template.ts):

export class RepeaterTemplate {
  friends: Set<string> = new Set(['Alice', 'Bob', 'Carol', 'Dana']);
}

Template (repeater-template.html):

<template>
  <p repeat.for="friend of friends">
    Hello, ${friend}!
  </p>
</template>

Iterating Maps

Maps offer a powerful way to iterate key-value pairs. Aurelia lets you deconstruct the map entry directly in the template.

Component (repeater-template.ts):

export class RepeaterTemplate {
  friends = new Map([
    ['Hello', { name: 'Alice' }],
    ['Hola', { name: 'Bob' }],
    ['Ni Hao', { name: 'Carol' }],
    ['Molo', { name: 'Dana' }]
  ]);
}

Template (repeater-template.html):

<p repeat.for="[greeting, friend] of friends">
  ${greeting}, ${friend.name}!
</p>

Here, [greeting, friend] splits each map entry so you can access both the key (greeting) and value (friend).

Iterating Objects via Value Converters

Objects aren’t directly iterable in Aurelia. To iterate over an object’s properties, convert it into an iterable format using a value converter.

Creating a Keys Value Converter

// resources/value-converters/keys.ts
export class KeysValueConverter {
  toView(obj: object): string[] {
    return Reflect.ownKeys(obj) as string[];
  }
}

Using the Converter in a Template

<import from="resources/value-converters/keys"></import>

<p repeat.for="key of friends | keys">
  ${key}, ${friends[key].name}!
</p>

The keys converter transforms the object into an array of its keys, making it iterable by repeat.for.

Custom Collection Handling with Repeat Handlers

Aurelia’s repeat system is extensible. If you need to iterate over non-standard collections (like HTMLCollections, NodeLists, or FileLists), you can create a custom repeat handler by implementing the IRepeatableHandler interface.

Custom Handler Example

import Aurelia, { Registration, IRepeatableHandler } from 'aurelia';

class ArrayLikeHandler implements IRepeatableHandler {
  static register(container) {
    Registration.singleton(IRepeatableHandler, ArrayLikeHandler).register(container);
  }

  handles(value: any): boolean {
    return 'length' in value && typeof value.length === 'number';
  }

  iterate(items: any, callback: (item: any, index: number) => void): void {
    for (let i = 0, len = items.length; i < len; i++) {
      callback(items[i], i);
    }
  }
}

Aurelia.register(
  ArrayLikeHandler,
  // other registrations
).app(MyApp).start();

Tip: Aurelia provides a default ArrayLikeHandler you can import directly:

Copy

import Aurelia, { ArrayLikeHandler } from 'aurelia';

Custom Handler Resolver

If you need to override the default order in which Aurelia selects a repeat handler, you can implement your own IRepeatableHandlerResolver:

class MyRepeatableHandlerResolver {
  resolve(value: any) {
    if (typeof value?.length === 'number') {
      return {
        iterate(items, callback) {
          for (let i = 0; i < items.length; ++i) {
            callback(items[i], i, items);
          }
        }
      };
    }
    throw new Error('The repeater supports only array-like objects.');
  }
}

This custom resolver can redefine how different collection types are handled by the repeater.

Summary

Aurelia 2’s list rendering capabilities are both powerful and flexible:

• Versatile Iteration: Work with arrays, sets, maps, ranges, and even objects (via converters).

• Efficient Updates: Use keyed iteration to minimize DOM changes.

• Contextual Data: Access properties like $index, $first, $last, $even, $odd, $length, and $parent for richer templates.

• Extensibility: Create custom handlers and resolvers to support any iterable data structure.

Mastering these features enables you to build dynamic, efficient UIs that handle complex data sets with ease.

Value converters transform data as it flows between your view and view model. They’re ideal for formatting text, dates, currencies, and more. In other frameworks, you might know them as pipes.

Data Flow

Converters work in two directions:

• toView: Prepares model data for display.

• fromView: Adjusts view data before updating the model (useful with two-way binding).

Both methods receive the primary value as the first argument, with any extra arguments used as configuration.

Example Methods

// toView: from model to view
toView(value, ...args) { /* transform value for display */ }

// fromView: from view to model
fromView(value, ...args) { /* transform value for the model */ }

Applying Converters in Templates

Use the pipe symbol (|) to attach a converter:

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

A matching converter might be:

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

Chaining Converters

You can chain multiple converters by separating them with additional pipes:

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

Passing Parameters

Pass parameters using a colon (:). Parameters can be:

• Static:

  Copy

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

• Bound:

  Copy

  <h1>${someValue | date:format}</h1>

  Copy

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

• Object-based:

  Copy

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

In both toView and fromView, the second parameter will be the passed configuration.

Creating Custom Value Converters

A converter is a simple class. Always reference it in camelCase within templates.

A no-op converter example:

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

Date Formatter Example

This converter formats dates based on locale:

import { valueConverter } from 'aurelia';

@valueConverter('date')
export class FormatDate {
  toView(value: string, locale = 'en-US') {
    const date = new Date(value);
    if (Number.isNaN(date.valueOf())) {
      return 'Invalid Date';
    }
    return new Intl.DateTimeFormat(locale, {
      month: 'long',
      day: 'numeric',
      year: 'numeric',
      timeZone: 'UTC'
    }).format(date);
  }
}

Import it in your view:

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

Usage examples:

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

View this in action on StackBlitz.

More Converter Examples

Currency Formatter

Formats numbers as currency strings.

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

Replaces keywords with 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

Transforms text into “1337” speak.

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 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 Converter

Adds ordinal suffixes to numbers (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

Transforms text into 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 examples highlight the flexibility of Aurelia 2's value converters. Experiment with your own transformations to tailor data exactly as you need it.

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:

<div if.bind="isLoading">Loading...</div>

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:

<div if.bind="user.isAuthenticated">Welcome back, ${user.name}!</div>
<div else>Please log in.</div>

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

<custom-element if="value.bind: canShowElement; cache: false"></custom-element>

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.

<div show.bind="isDataLoaded">Data loaded successfully!</div>

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:

enum Status {
  Received   = 'received',
  Processing = 'processing',
  Dispatched = 'dispatched',
  Delivered  = 'delivered',
  Unknown    = 'unknown',
}

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

<template switch.bind="orderStatus">
  <span case="received">Order received.</span>
  <span case="processing">Processing your order.</span>
  <span case="dispatched">On the way.</span>
  <span case="delivered">Delivered.</span>
  <span default-case>Status unknown.</span>
</template>

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:

<template switch.bind="orderStatus">
  <span case.bind="['received', 'processing']">Order is being processed.</span>
  <span case="dispatched">On the way.</span>
  <span case="delivered">Delivered.</span>
</template>

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:

<template switch.bind="orderStatus">
  <span case="received" fall-through.bind="true">Order received.</span>
  <span case="processing">Order is being processed.</span>
  <!-- Other cases -->
</template>

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:

<template repeat.for="num of 100">
  <template switch.bind="true">
    <span case.bind="num % 3 === 0 && num % 5 === 0">FizzBuzz</span>
    <span case.bind="num % 3 === 0">Fizz</span>
    <span case.bind="num % 5 === 0">Buzz</span>
  </template>
</template>

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:

<template as-custom-element="foo-bar">
  <au-slot name="s1"></au-slot>
</template>

<foo-bar>
  <template au-slot="s1" switch.bind="status">
    <span case="received">Order received.</span>
    <span case="dispatched">On the way.</span>
    <span case="processing">Processing your order.</span>
    <span case="delivered">Delivered.</span>
  </template>
</foo-bar>

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:

<template>
  <let day.bind="2"></let>
  <template switch.bind="status">
    <span case="received">Order received.</span>
    <span case="dispatched">On the way.</span>
    <span case="processing">Processing your order.</span>
    <span case="delivered" switch.bind="day">
      Expected to be delivered
      <template case.bind="1">tomorrow.</template>
      <template case.bind="2">in 2 days.</template>
      <template default-case>in a few days.</template>
    </span>
  </template>
</template>

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:

<!-- Incorrect: `case` outside of `switch` context -->
<span case="foo"></span>

<!-- Incorrect: `case` not a direct child of `switch` -->
<template switch.bind="status">
  <template if.bind="someCondition">
    <span case="delivered">Delivered</span>
  </template>
</template>

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.

Aurelia 2 significantly simplifies the handling of Promises directly within your templates. Unlike previous versions where promise resolution typically occurred in the view model, Aurelia 2 empowers you to manage asynchronous operations directly in the view.

This is accomplished through the promise.bind template controller. It intelligently manages the different states of a Promise: pending, resolved (then), and rejected (catch). This approach reduces boilerplate code and makes asynchronous data handling in templates more declarative and intuitive.

Basic Usage

The promise.bind attribute allows you to bind a Promise to a template, rendering different content based on the Promise's current state.

<div promise.bind="myPromise">
  <template pending>Loading data...</template>
  <template then="data">Data loaded: ${data}</template>
  <template catch="error">Error: ${error.message}</template>
</div>

In this example:

• promise.bind="myPromise": Binds the div to the Promise named myPromise in your view model.

• <template pending>: Content rendered while myPromise is in the pending state (still resolving).

• <template then="data">: Content rendered when myPromise resolves successfully. The resolved value is available as data within this template.

• <template catch="error">: Content rendered if myPromise rejects. The rejection reason (typically an Error object) is available as error.

Simple Example with Different Promise States

Let's illustrate with a view model that manages different promise scenarios:

<div>
  <h3>Promise Example 1</h3>
  <div promise.bind="promise1">
    <template pending>Promise 1: Loading...</template>
    <template then="data">Promise 1: Resolved with: ${data}</template>
    <template catch="err">Promise 1: Rejected with error: ${err.message}</template>
  </div>
</div>

<div>
  <h3>Promise Example 2 (No data in 'then' state)</h3>
  <div promise.bind="promise2">
    <template pending>Promise 2: Waiting...</template>
    <template then>Promise 2: Successfully Resolved!</template>
    <template catch>Promise 2: An error occurred!</template>
  </div>
</div>

export class MyApp {
  promise1: Promise<string>;
  promise2: Promise<void>;

  constructor() {
    this.promise1 = this.createDelayedPromise('Promise 1 Data', 2000, true); // Resolves after 2 seconds
    this.promise2 = this.createDelayedPromise(undefined, 3000, false); // Rejects after 3 seconds
  }

  createDelayedPromise(data: any, delay: number, shouldResolve: boolean): Promise<any> {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        if (shouldResolve) {
          resolve(data);
        } else {
          reject(new Error('Promise rejected after delay'));
        }
      }, delay);
    });
  }
}

In this example, promise1 is set to resolve after 2 seconds, and promise2 is set to reject after 3 seconds. The template dynamically updates to reflect each promise's state. Notice in promise2's then template, we don't specify a variable, indicating we only care about the resolved state, not the resolved value itself.

Promise Binding with Functions and Parameters

You can directly bind a function call to promise.bind. Aurelia is smart enough to re-invoke the function only when its parameters change, treating function calls in templates as pure operations.

The following example fetches a random advice slip from an API each time a button is clicked:

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

<div promise.bind="fetchAdvice(adviceIndex)">
  <span pending>Fetching advice...</span>
  <span then="adviceData">
    Advice ID: ${adviceData.slip.id}<br>
    "${adviceData.slip.advice}"
    <button click.trigger="adviceIndex = adviceIndex + 1">Get New Advice</button>
  </span>
  <span catch="fetchError">
    Failed to get advice. Error: ${fetchError}
    <button click.trigger="adviceIndex = adviceIndex + 1">Try Again</button>
  </span>
</div>

export class MyApp {
  adviceIndex = 0; // Initialize adviceIndex

  fetchAdvice(index: number): Promise<any> {
    // 'index' parameter ensures function re-execution on parameter change
    console.log(`Fetching advice, attempt: ${index}`);
    return fetch("https://api.adviceslip.com/advice", {
      cache: 'no-store' // Prevents caching for example clarity
    })
    .then(response => response.ok
      ? response.json()
      : Promise.reject(new Error(`HTTP error! status: ${response.status}`))
    )
    .catch(error => {
      console.error("Fetch error:", error);
      throw error; // Re-throw to be caught by the promise template
    });
  }
}

Key Points:

• adviceIndex: This variable, initialized with let adviceIndex.bind="0", acts as a parameter to fetchAdvice. Incrementing adviceIndex via the button click triggers Aurelia to re-evaluate fetchAdvice(adviceIndex).

• Function Re-execution: Aurelia re-executes fetchAdvice only when adviceIndex changes, ensuring efficient handling of function-based promises.

• Error Handling: The .catch template gracefully handles fetch errors, providing user-friendly feedback and a "Try Again" button.

Isolated Promise Binding Scope

The promise.bind template controller creates its own isolated scope. This is crucial to prevent naming conflicts and unintended modification of the parent view model or scope.

<div promise.bind="userPromise">
  <template then="userData">
    <user-profile user-data.bind="userData"></user-profile>
    <p>User ID within promise scope: ${userData.id}</p>
    <!-- Accessing parent scope (if needed, though generally discouraged) -->
    <!-- <p>Some parent property: ${$parent.someProperty}</p> -->
  </template>
  <template catch="userError">
    <error-display error-message.bind="userError.message"></error-display>
  </template>
</div>

In this example:

• userData and userError: These variables are scoped only within the promise.bind context. They do not pollute the parent view model scope.

• Component Communication: To pass data to child components (like <user-profile>), use property binding (e.g., user-data.bind="userData").

• Parent Scope Access (Discouraged): While you can access the parent scope using $parent, it's generally better to manage data flow through explicit bindings and avoid relying on parent scope access for maintainability.

Nested Promise Bindings

Aurelia 2 supports nesting promise.bind controllers to handle scenarios where one asynchronous operation depends on the result of another.

<div promise.bind="initialFetchPromise">
  <template pending>Fetching initial data...</template>
  <template then="initialResponse" promise.bind="initialResponse.json()">
    <template then="jsonData">
      Data received and deserialized: ${jsonData.name}
    </template>
    <template catch="jsonError">
      Error deserializing JSON: ${jsonError.message}
    </template>
  </template>
  <template catch="fetchError">
    Error fetching initial data: ${fetchError.message}
  </template>
</div>

Flow of Execution:

1. initialFetchPromise: The outer promise.bind starts with initialFetchPromise.

2. Pending State: While initialFetchPromise is pending, "Fetching initial data..." is displayed.

3. First then (Response): When initialFetchPromise resolves, the resolved value (initialResponse) becomes available in the then template.

4. Nested promise.bind (JSON Deserialization): Inside the first then template, a nested promise.bind is used: promise.bind="initialResponse.json()". This starts a new promise based on deserializing the initialResponse.

5. Nested then (JSON Data): When initialResponse.json() resolves, the parsed JSON data (jsonData) is available in this then template. "Data received and deserialized: ${jsonData.name}" is displayed.

6. Nested catch (JSON Error): If initialResponse.json() fails (e.g., invalid JSON), the nested catch template handles the error.

7. Outer catch (Fetch Error): If initialFetchPromise initially rejects, the outer catch template handles the initial fetch error.

Promise Bindings in repeat.for Loops

When using promise.bind within a repeat.for loop, it's crucial to manage scope correctly, especially if you need to access data from each promise iteration. Using let bindings within the <template promise.bind="..."> is highly recommended to create proper scoping for each iteration.

<let promiseItems.bind="[[42, true], ['error-string', false], ['success-string', true]]"></let>
<ul>
  <template repeat.for="item of promiseItems">
    <li>
      <template promise.bind="createPromise(item[0], item[1])">
        <let itemData.bind="null"></let> <let itemError.bind="null"></let>
        <span pending>Processing item...</span>
        <span then="itemData">Item processed successfully: ${itemData}</span>
        <span catch="itemError">Item processing failed: ${itemError.message}</span>
      </template>
    </li>
  </template>
</ul>

export class MyApp {
  promiseItems: any[][]; // Defined in HTML using <let>

  createPromise(value: any, shouldResolve: boolean): Promise<any> {
    return new Promise((resolve, reject) => {
      setTimeout(() => {
        if (shouldResolve) {
          resolve(value);
        } else {
          reject(new Error(`Promise rejected for value: ${value}`));
        }
      }, 1000); // Simulate async processing
    });
  }
}

Importance of <let> Bindings:

• Scoped Context: The lines <let itemData.bind="null"></let> and <let itemError.bind="null"></let> inside the promise.bind template are essential. They create itemData and itemError properties in the overriding context of each promise.bind iteration.

• Preventing Overwriting: Without these let bindings, itemData and itemError would be created in the binding context, which is shared across all iterations of the repeat.for loop. This would lead to data from later iterations overwriting data from earlier ones, resulting in incorrect or unpredictable behavior.

• Correct Output: With let bindings, each iteration of the repeat.for loop gets its own isolated scope for itemData and itemError, ensuring correct rendering for each promise in the list.

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.

Handling forms and user input is a common task in most applications. Whether you are building a login form, a data-entry screen, or even a chat interface, Aurelia makes it intuitive to work with forms. By default, Aurelia’s binding system uses two-way binding for form elements (like <input>, <textarea>, and contenteditable elements), which keeps your view and model in sync automatically.

Data Flow in Forms

Aurelia’s two-way binding updates your view model properties whenever users enter data into form elements, and likewise updates the form elements if the view model changes:

1. The user types in the input (e.g., John).

2. The native input events fire. Aurelia observes the value change.

3. The binding system updates the corresponding view model property.

4. Any references to that property automatically reflect its new value.

Because of this automatic synchronization, you generally don’t need to write custom event handlers or watchers to track form inputs.

Creating a Basic Form

Aurelia lets you create forms in pure HTML without any special setup. Here’s a simple login form illustrating how little code is required.

<form submit.trigger="handleLogin()">
  <div>
    <label for="email">Email:</label>
    <input id="email" type="text" value.bind="email" />
  </div>
  <div>
    <label for="password">Password:</label>
    <input id="password" type="password" value.bind="password" />
  </div>

  <button type="submit">Login</button>
</form>

Key Points:

• We created a form with two inputs: email and password.

• The value.bind syntax binds these inputs to class properties named email and password.

• We call a handleLogin() method on submit to process the form data.

And here is the view model (login-component.ts):

export class LoginComponent {
  private email = "";
  private password = "";

  handleLogin() {
    // Validate credentials or call an API
    console.log(`Email: ${this.email}, Password: ${this.password}`);
  }
}

Whenever the email or password fields change in the UI, their corresponding view model properties are updated. Then, in handleLogin(), you can handle form submission however you wish.

Binding With Text and Textarea Inputs

Text Input

Binding to text inputs in Aurelia is straightforward:

<form>
  <label>User value:</label><br />
  <input type="text" value.bind="userValue" />
</form>

You can also bind other attributes like placeholder:

<form>
  <label>User value:</label><br />
  <input type="text" value.bind="userValue" placeholder.bind="myPlaceholder" />
</form>

Textarea

Textareas work just like text inputs, with value.bind for two-way binding:

<form>
  <label>Comments:</label><br />
  <textarea value.bind="textAreaValue"></textarea>
</form>

Any changes to textAreaValue in the view model will show up in the <textarea>, and vice versa.

Binding with Checkbox Inputs

Aurelia supports two-way binding for checkboxes in various configurations.

Booleans

Bind a boolean property to the checked attribute:

export class MyApp {
  motherboard = false;
  cpu = false;
  memory = false;
}

<form>
  <h4>Products</h4>
  <label
    ><input type="checkbox" checked.bind="motherboard" /> Motherboard</label
  >
  <label><input type="checkbox" checked.bind="cpu" /> CPU</label>
  <label><input type="checkbox" checked.bind="memory" /> Memory</label>

  motherboard = ${motherboard}<br />
  cpu = ${cpu}<br />
  memory = ${memory}<br />
</form>

Array of Numbers

When using checkboxes as a multi-select, bind an array to each input’s checked attribute. Provide a model for each checkbox to indicate its value:

export class MyApp {
  products = [
    { id: 0, name: "Motherboard" },
    { id: 1, name: "CPU" },
    { id: 2, name: "Memory" },
  ];

  selectedProductIds = [];
}

<form>
  <h4>Products</h4>
  <label repeat.for="product of products">
    <input
      type="checkbox"
      model.bind="product.id"
      checked.bind="selectedProductIds"
    />
    ${product.id} - ${product.name}
  </label>
  <br />
  Selected product IDs: ${selectedProductIds}
</form>

Array of Objects

Numbers aren’t the only value type you can store. Here’s how to manage an array of objects:

export interface IProduct {
  id: number;
  name: string;
}

export class MyApp {
  products: IProduct[] = [
    { id: 0, name: "Motherboard" },
    { id: 1, name: "CPU" },
    { id: 2, name: "Memory" },
  ];
  selectedProducts: IProduct[] = [];
}

<form>
  <h4>Products</h4>
  <label repeat.for="product of products">
    <input
      type="checkbox"
      model.bind="product"
      checked.bind="selectedProducts"
    />
    ${product.id} - ${product.name}
  </label>

  Selected products:
  <ul>
    <li repeat.for="product of selectedProducts">
      ${product.id} - ${product.name}
    </li>
  </ul>
</form>

Array of Objects with Matcher

If your objects do not share reference equality (e.g., same data, different instances), define a custom matcher:

export class MyApp {
  selectedProducts = [
    { id: 1, name: "CPU" },
    { id: 2, name: "Memory" },
  ];

  productMatcher = (a, b) => a.id === b.id;
}

<form>
  <h4>Products</h4>
  <label>
    <input
      type="checkbox"
      model.bind="{ id: 0, name: 'Motherboard' }"
      matcher.bind="productMatcher"
      checked.bind="selectedProducts"
    />
    Motherboard
  </label>
  ...
</form>

Array of Strings

If your “selected items” array holds strings, you can rely on the standard value attribute:

export class MyApp {
  products = ["Motherboard", "CPU", "Memory"];
  selectedProducts = [];
}

<form>
  <h4>Products</h4>
  <label repeat.for="product of products">
    <input
      type="checkbox"
      value.bind="product"
      checked.bind="selectedProducts"
    />
    ${product}
  </label>
  <br />
  Selected products: ${selectedProducts}
</form>

Binding with Radio Inputs

Radio groups in Aurelia are similarly straightforward. Only one radio button in a group can be checked at a time.

Numbers

export class MyApp {
  products = [
    { id: 0, name: "Motherboard" },
    { id: 1, name: "CPU" },
    { id: 2, name: "Memory" },
  ];
  selectedProductId = null;
}

<form>
  <h4>Products</h4>
  <label repeat.for="product of products">
    <input
      type="radio"
      name="group1"
      model.bind="product.id"
      checked.bind="selectedProductId"
    />
    ${product.id} - ${product.name}
  </label>
  <br />
  Selected product ID: ${selectedProductId}
</form>

Objects

export class MyApp {
  products = [
    { id: 0, name: "Motherboard" },
    { id: 1, name: "CPU" },
    { id: 2, name: "Memory" },
  ];
  selectedProduct = null;
}

<form>
  <h4>Products</h4>
  <label repeat.for="product of products">
    <input
      type="radio"
      name="group2"
      model.bind="product"
      checked.bind="selectedProduct"
    />
    ${product.id} - ${product.name}
  </label>
  Selected product: ${selectedProduct.id} - ${selectedProduct.name}
</form>

Objects with Matcher

If the selected object doesn’t share reference equality, define a custom matcher:

export class MyApp {
  selectedProduct = { id: 1, name: "CPU" };
  productMatcher = (a, b) => a.id === b.id;
}