What is Aurelia?

Aurelia is the web framework that feels native to the browser. Built on web standards with zero overhead from virtual DOMs or magic abstractions, Aurelia delivers exceptional performance while keeping your code clean and maintainable.

Why developers choose Aurelia:

• Efficient bundle sizes with smart code splitting and async loading

• Standards-based architecture that leverages browser capabilities

• TypeScript-first with powerful dependency injection built-in

• No breaking changes since 2.0 - stable, production-ready platform

If you value web standards, performance, and developer experience over framework hype, Aurelia is built for you.

👋 New to Aurelia? Start with our - build a real app in 15 minutes.

🔧 Want the concepts first? Begin with for focused introduction to core concepts.

🚀 Migrating from another framework?

• - Better performance, cleaner code

• - All the simplicity, better performance

• - Keep the good, lose the complexity

⚡ Just want to see it work? Try our for immediate setup.

• Direct DOM manipulation - no virtual DOM overhead

• Batched rendering for optimal browser performance

• Efficient memory usage - applications that don't drain batteries

• Web Components foundation - build for the future of the web

• Modern JavaScript/TypeScript - no proprietary abstractions

• Seamless third-party integration - works with any library

• Powerful dependency injection built-in, no external libraries needed

• Two-way data binding with unidirectional safety

• Complete ecosystem - routing, validation, i18n, testing, CLI

• Used by enterprise companies worldwide

• MIT licensed open-source with active development

• Comprehensive testing tools built-in

Aurelia isn't chasing the latest trends - it's built on the fundamental technologies that power the web. By embracing web standards and leveraging browser capabilities, Aurelia applications are inherently future-proof and performant.

Our focused approach means:

• Thoughtful feature development - every addition serves a clear purpose

• Direct access to the core team - your feedback directly shapes the framework

• Stable, reliable releases - no breaking changes that disrupt your projects

Aurelia delivers superior performance by working directly with the browser's DOM instead of creating unnecessary abstraction layers.

Performance Advantages:

• Zero virtual DOM overhead - no diffing algorithms or reconciliation cycles

• Faster rendering - direct updates where they're needed

• Smaller memory footprint - no duplicate DOM trees in memory

Developer Benefits:

• Predictable behavior - work directly with web platform APIs

• Easier debugging - inspect actual DOM elements, not virtual representations

• Better third-party integration - no compatibility issues with DOM-based libraries

Modern browsers are incredibly fast at DOM manipulation. Aurelia's intelligent observation and batching system ensures you get maximum performance without the complexity and overhead of virtual DOM solutions.

Start Here:

1. - Build your first app in 15 minutes

2. - Core concepts explained clearly

3. - Build reusable UI components

Build Real Apps: 4. - Master Aurelia's powerful templating 5. - Add navigation to your applications 6. - Handle user input effectively 7. - Test your applications thoroughly 8. - Optimize for production 9. - Complex application patterns

Need Help? Join our or check for support.

Ready to contribute or need support? The Aurelia community welcomes developers of all skill levels.

Get Support:

• - Real-time chat with the community

• - Q&A and feature discussions

• - Technical questions and answers

Contribute:

• - How to contribute code and documentation

• - Report bugs or request features

• - Help improve these docs

Jump into our and build your first Aurelia application in 15 minutes. You'll be amazed at how intuitive and powerful web development can be with the right tools.

Aurelia is a modern JavaScript framework that empowers you to build exceptional web applications with clean, maintainable code. If you're familiar with HTML, CSS, and modern JavaScript/TypeScript, this essentials guide will introduce you to Aurelia's core concepts and get you productive quickly.

This section provides a practical overview of Aurelia's fundamental building blocks. Each concept links to comprehensive documentation where you can dive deeper, but these essentials give you everything needed to start building with confidence.

What Makes Aurelia Different

Aurelia stands out by embracing web standards and keeping things simple:

• Standards-based: Built on modern web standards without unnecessary abstractions

• Convention over configuration: Intuitive patterns that reduce boilerplate

• Powerful templating: Rich binding system with excellent performance

• Dependency injection: Clean, testable architecture out of the box

Components are the building blocks of your Aurelia application. Learn how to create reusable UI elements with clean separation between view and view-model logic.

Aurelia's templating system provides powerful data binding, event handling, and conditional rendering with a syntax that feels natural and expressive.

Aurelia's dependency injection system promotes clean architecture by managing your application's services and their dependencies automatically.

Understand how Aurelia's observation system automatically tracks changes and updates your UI efficiently without virtual DOM overhead.

Ready to build something? Try our to create your first Aurelia application. For comprehensive coverage of all features, explore the full documentation sections on , , and .

The section contains step-by-step guides for building real applications, while covers advanced topics and best practices.

In this step you will create the project, enable the router, and build a shared layout component.

1. Create the project

npx makes aurelia
# Name: project-pulse
# Select TypeScript
cd project-pulse
npm run dev

2. Enable the router and active link styling

Update src/main.ts to register the router and configure an active class for navigation links:

import Aurelia from 'aurelia';
import { RouterConfiguration } from '@aurelia/router';
import { MyApp } from './my-app';

Aurelia
  .register(RouterConfiguration.customize({ activeClass: 'is-active' }))
  .app(MyApp)
  .start();

Any <a load="..."> link will now get the is-active class when the route is active.

3. Create the app shell

Create the folders src/components and src/pages if you do not have them yet.

Create src/components/app-shell.ts:

Create src/components/app-shell.html:

Next step:

with is a template controller that creates a new binding scope for its content. It’s useful when you want to “zoom in” on an object so you don’t have to repeat a prefix like user. everywhere.

Basic usage

<template with.bind="user">
  <h2>${firstName} ${lastName}</h2>
  <p>${email}</p>
</template>

The inner template’s binding context becomes user, so firstName resolves as user.firstName, etc.

You can also put with.bind on a real element:

<section with.bind="user">
  <h2>${firstName} ${lastName}</h2>
</section>

“Shape” a small context object

Sometimes you don’t want to pass the whole object through — just a few values (or renamed values):

• with does not add/remove DOM like if or repeat.

• When the with value changes, Aurelia re-binds the existing view to the new scope (it does not recreate the view).

• with expects an object. If your value can be null/undefined, guard it:

• Prefer <let> when you only need a couple of local aliases and don’t need to re-scope a whole block.

focus is a built-in custom attribute that lets you bind an element’s focus state to a view-model property.

By default it’s two-way:

• setting the property focuses/blurs the element

• focusing/blurring the element updates the property

Basic usage (two-way)

<input focus.bind="isFocused">

<button click.trigger="isFocused = true">Focus the input</button>
<button click.trigger="isFocused = false">Blur the input</button>

export class MyPage {
  public isFocused = false;
}

One-way focus (recommended for “open a thing, focus an input”)

Two-way focus can be surprising if you don’t want a blur to change your state. In that case, make it one-way:

Now the input won’t write back to shouldFocusSearch when it blurs.

• The target must be focusable. For non-input elements, you may need tabindex="0".

• Focusing can only happen once the element is connected to the document; focus handles this automatically (it will apply focus after attach if needed).

In this step you will listen to router events and surface navigation state in the UI.

Update src/pages/projects-page.ts:

Update src/pages/projects-page.html:

You now have:

• Root routes and child routes

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.

If you need even finer control, dive into the focused guides linked throughout this section—for example, for forcing one-time/one-way flow on demand, or the new

Most of the time, when working with templated views in Aurelia, you want to create reusable components. However, there are scenarios where reusability isn’t necessary or might cause unnecessary overhead. Local (inline) templates allow you to define a template as a "one-off" custom element, usable only within the scope of its parent view. This helps reduce boilerplate and fosters clear, localized organization of your code.

By defining <template as-custom-element="person-info">, you create a local component named person-info, which can only be used in this file (my-app.html). It accepts a bindable property person (specified via the <bindable> tag). You can now reuse <person-info> repeatedly in this view without creating a separate file or global custom element.

Local templates are similar to HTML-Only Custom Elements, with the major difference that local templates are scoped to the file that defines them. They are ideal for:

In this step you will create the root pages and a Projects layout that hosts child routes.

1. Create the dashboard

Create src/pages/dashboard-page.ts:

export class DashboardPage {}

Create src/pages/dashboard-page.html:

<import from="../components/app-shell"></import>

<app-shell>
  <h1 au-slot="title">Dashboard</h1>
  <a au-slot="actions" load="../projects">View Projects</a>

  <p>Welcome to Project Pulse. Use the Projects page to manage tasks.</p>
</app-shell>

Note: Links inside routed components are resolved relative to the current route. Use ../ when you want to navigate to a sibling at the parent level.

2. Create placeholder child pages

We will build these pages in later steps, but we need the files now so the routes can resolve.

Create src/pages/projects-overview-page.ts:

Create src/pages/projects-overview-page.html:

Create src/pages/projects-activity-page.ts:

Create src/pages/projects-activity-page.html:

Create src/pages/projects-page.ts:

Create src/pages/projects-page.html:

The nested <au-viewport> is where the Overview and Activity pages render.

Update src/my-app.ts:

Update src/my-app.html:

Notice the is-active class when you navigate between Dashboard and Projects.

Next step:

In this step you will add a parameterized detail route and guard it with canLoad and canUnload.

1. Add the detail route

Update src/pages/projects-page.ts to add the detail child route:

import { route } from '@aurelia/router';
import { ProjectDetailPage } from './project-detail-page';
import { ProjectsActivityPage } from './projects-activity-page';
import { ProjectsOverviewPage } from './projects-overview-page';

@route({
  routes: [
    { path: ['', 'overview'], component: ProjectsOverviewPage, title: 'Overview' },
    { path: 'activity', component: ProjectsActivityPage, title: 'Activity' },
    { id: 'project-detail', path: 'detail/:id', component: ProjectDetailPage, title: 'Project Detail' }
  ]
})
export class ProjectsPage {}

We keep detail in the URL to keep the child routes explicit and readable. The id: 'project-detail' value is what the Overview page uses in its route: instruction, with a ../ prefix to resolve against the parent context.

Create src/pages/project-detail-page.ts:

Create src/pages/project-detail-page.html:

Guard recap:

• canLoad prevents invalid IDs and redirects to projects.

• canUnload prompts when there is unsaved user input.

Next step:

This section contains practical, real-world examples of building reusable UI components in Aurelia. Each recipe shows you how to create a complete, production-ready component from scratch.

What You'll Find Here

These recipes demonstrate:

• Best practices for component architecture

• Accessibility considerations

• TypeScript with proper typing

• Testing patterns for each component

• Real-world features and edge cases

• : A fully-featured dropdown with keyboard navigation and accessibility

• : A flexible modal system with backdrop, animations, and focus management

• : An accessible tab interface with dynamic content

Each recipe includes:

1. Overview: What the component does and when to use it

2. Complete Code: TypeScript and HTML for the component

3. Usage Examples: How to consume the component

These recipes assume you're familiar with:

All recipes follow Aurelia 2 best practices:

• Use resolve() for dependency injection (not decorators)

• No <template> wrappers in HTML files

• Named exports for reusable components

Have a component recipe you'd like to share? Contributions are welcome! Make sure your recipe includes:

• Complete, working code

• Accessibility considerations

• Usage examples

• Tests

Ready to build something? Pick a recipe and start coding!

Build a small but realistic app while learning the Aurelia router, component communication, and real-world navigation patterns.

What you will build

• A Dashboard and a Projects area

• Nested routes for Projects (Overview + Activity)

• A project detail view with route parameters

• Filterable lists with query params you can share

• Router events and active navigation styling

• Multi-locale internationalization (i18n)

• Form validation with localized error messages

• Modal dialogs for confirmations and editing

• Centralized state management

• Completed the

• Basic TypeScript and HTML

If you are new to Aurelia, start with steps 1–4 to learn routing fundamentals. Steps 5–6 cover advanced routing patterns. Steps 7–10 introduce additional Aurelia packages for building production-ready applications.

Get Aurelia up and running in 5 minutes or less.

• A code editor of your choice

• (latest version recommended) for the scaffolded app path

Want to try Aurelia immediately without installing anything? Use . That page is the canonical no-build setup and covers module scripts, CDN imports, version pinning, CodePen usage, and package registration.

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.

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 . Download the installer for your operating system and then follow the prompts.

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

Aurelia's templating system provides powerful data binding, event handling, and control flow with intuitive syntax. Templates are HTML files enhanced with binding expressions and template controls.

Display dynamic content using string interpolation:

Bind to element properties and attributes:

Create two-way data flow with .bind:

As you type, both the input and paragraph update automatically.

Handle user interactions with .trigger:

Build your first Aurelia app in 10 minutes! This complete guide takes you from zero to a working interactive application with live data binding.

An interactive hello world app where typing in a text field instantly updates the greeting. No page refreshes, no complex setup - just pure Aurelia magic.

• Recent version of installed

• Basic knowledge of JavaScript, HTML, and CSS

Aurelia supports two different spread features in templates:

1. Bindables spreading: bind multiple properties from an object onto a custom element’s bindable properties.

2. Attribute transferring: forward captured attributes/bindings from a custom element usage to an element inside its template.

This page focuses on the template syntax and common gotchas. For the deeper conceptual guide, see:

Attribute mapping is Aurelia's way of keeping template syntax concise. After an attribute pattern parses the attribute name but before a binding command emits instructions, the mapper answers two questions:

1. Which DOM property does this attribute target?

2. Should .bind implicitly behave like .two-way for this attribute?

Class and style bindings in Aurelia allow you to bind to CSS properties and add one or more classes to your HTML elements inside of your views.

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

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 conditionally display, for example, 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.

These are our fighting words

The web development industry has lost its mind. Frameworks reinvent perfectly good web standards. Developers rewrite applications every eighteen months to chase the new hotness. Testing requires PhD-level framework knowledge just to mock a simple service.

We refuse to participate in this insanity.

We believe frameworks should enhance the web, not replace it. We believe your knowledge should compound, not expire. We believe testing should be trivial, not heroic.

Most importantly, we believe you shouldn't have to forget everything you know about web development just to use our framework.

These beliefs have made us unfashionable. Good. We'd rather be right than trendy.

Why Not Just Use React?

Because the biggest crowd is not the only path to victory.

React is the industry default. It commands stadium keynotes, spawns endless packages, and fills job boards with requirements. We salute the React team for making component thinking mainstream and showing the browser can power ambitious interfaces. That legacy is undeniable.

But scale changes the game. React's strength is modular freedom. Every decision, from routing to state management to forms to dependency injection to testing, invites you to draft your own lineup of supporting libraries. That freedom can be exhilarating. It can also demand constant attention as packages shift, maintainers rotate out, and best practices rewrite themselves overnight. Teams do not just learn React; they learn React plus the custom stack they assembled on day one and have to re-evaluate each quarter.

Aurelia stays intentionally smaller so we can ship the essentials as one cohesive strike force. Our router, dependency injection, binding engine, and testing story are forged together by the same team with the same philosophy. You spend your energy shipping features, not benchmarking which combination of libraries will still be supported next quarter. When we add capability, we do it without erasing the knowledge you already earned.

Choosing Aurelia means joining a community that prizes stability over hype, standards over novelty, and craftsmanship over churn. You gain direct access to maintainers who care about your use case, not just the next keynote demo. Our ecosystem is tighter, but it is aligned, predictable, and built to compound value release after release.

Use React if you want the world of mix-and-match options. Choose Aurelia if you want a unified framework that already lives the principles this manifesto defends.

We build on the web, not around it.

The web platform is brilliant. HTML gives us declarative markup that's intuitive to read and write. CSS provides powerful styling capabilities that scale from simple pages to complex applications. JavaScript offers a flexible, evolving language that runs everywhere. These aren't bugs to be fixed. They're features to be leveraged.

Yet somewhere along the way, the industry decided the web platform wasn't sophisticated enough for "real" applications. Everyone needed their own templating language that looked nothing like HTML. Their own styling solution that avoided CSS. Their own module system that ignored JavaScript's evolution. Learn our special syntax. Forget everything you know about web development. Trust us, we know better than the web standards committees and the collective wisdom of millions of developers.

This is breathtaking arrogance disguised as innovation.

Consider what this means in practice: A developer who's spent years mastering HTML, CSS, and JavaScript sits down with a modern framework and discovers that none of that knowledge applies. The templating syntax is completely foreign. The styling approach bypasses CSS entirely. The component model bears no resemblance to anything they've learned about web development.

We're essentially telling experienced web developers that their expertise is worthless. That the web platform they've mastered is inadequate. That they need to start over with our special way of doing things.

Aurelia takes the opposite approach. We enhance web standards instead of replacing them. Your templates are HTML with binding attributes that read like natural language: value.bind, click.trigger, repeat.for. A web developer can look at Aurelia templates and immediately understand what's happening, even if they've never seen the framework before.

Your components are JavaScript classes with predictable lifecycle methods. No magical decorators that fundamentally change how JavaScript works. No special compilation steps that transform your code into something unrecognizable. Just classes with methods that get called at logical points in the component's life.

Your styles are CSS. Not CSS-in-JS. Not a special styling language. Not a build-time transformation that generates CSS for you. Just CSS, working exactly like CSS should work, with all the power and flexibility you expect.

This philosophy extends to how we handle emerging standards. When Web Components were still experimental, we didn't bet the entire framework on them. When they became stable, we didn't ignore them. We built compatibility layers that let you use Aurelia components as Web Components when that makes sense, while keeping our core architecture independent of any single standard's success or failure.

We've watched frameworks rise and fall based on their alignment with web standards. The ones that fought against the platform eventually lost. The ones that embraced it survived and thrived. We're not just building for today's web. We're building for the web's long-term evolution.

When you learn Aurelia, you're not just learning a framework. You're deepening your understanding of the web platform itself. The binding concepts translate to vanilla JavaScript. The component patterns work with or without the framework. The architectural principles apply to any web application.

Your knowledge doesn't expire when the next framework revolution comes along. It compounds, making you a better web developer regardless of what tools you use next. That's the difference between building on the web platform and building around it.

Stop making the same decisions over and over.

Here's a thought experiment: How many different ways can you structure a web application? How many reasonable approaches are there to naming components, organizing files, or wiring up dependencies?

The answer is: a few good ways, and hundreds of terrible ways.

Yet modern web development has become obsessed with giving you infinite configuration options. Choose your file naming strategy from seventeen possibilities. Configure your binding syntax from forty-three variants. Set up your directory structure using our flexible, powerful, completely overwhelming configuration system. Make four hundred decisions before you can render "Hello World."

This is madness disguised as flexibility.

Consider what this means for a team. Every developer has their own preferences. The React developer wants JSX everywhere. The Vue developer prefers template syntax. The Angular developer expects decorators. The result? Endless bike-shedding discussions about tooling choices instead of productive work on actual features.

Or consider what this means for learning. A new developer doesn't just need to learn the framework. They need to learn your team's specific configuration choices, your particular file organization, your custom naming conventions. Every project becomes a unique snowflake with its own special setup.

Convention over configuration means we make the boring decisions so you don't have to. Create a file called user-profile.ts and another called user-profile.html, and you automatically get a <user-profile> component. Mark a property with @bindable, and a method called propertyChanged automatically becomes a change callback. Put components in a components folder, put services in a services folder, and everything just works.

These aren't arbitrary restrictions. They're carefully chosen defaults based on years of experience building real applications. We've seen what works and what doesn't. We've observed the patterns that emerge naturally when teams build maintainable applications. We've codified those patterns into conventions that guide you toward good practices.

But here's the crucial part: conventions should accelerate you, not constrain you. When you genuinely need something different, when your specific use case demands a different approach, every convention has an escape hatch. Need a custom component name? Use @customElement('custom-name'). Need different binding behavior? Configure it explicitly. Need a non-standard file organization? Override the defaults.

The key word is "earn." You have to consciously choose to deviate from the convention. You have to be explicit about what you want instead. This creates a natural pressure toward consistency while preserving flexibility for genuine edge cases.

Some developers hate this philosophy. They see conventions as limitations on their creativity. They want to configure every detail of the framework's behavior. They view our defaults as opinions imposed on their artistic vision.

We think they're optimizing for the wrong thing. Yes, you could spend three days configuring your perfect setup. You could create a unique file organization that perfectly reflects your mental model. You could customize every aspect of the framework's behavior to match your preferences.

But why? Your user registration component isn't fundamentally different from everyone else's. Your data binding requirements aren't uniquely artistic. Your architectural needs aren't so special that they require a completely novel approach.

Time spent on configuration is time not spent on features. Energy devoted to framework setup is energy not devoted to solving user problems. Cognitive load consumed by tooling choices is cognitive load unavailable for business logic.

Conventions are liberation from meaningless choices. They're shared understanding across teams and projects. They're productivity multipliers that let you focus on what actually matters: building great applications that solve real problems for real people.

Code should express intent, not implementation details.

Here's a simple test: Show a piece of code to someone who's never seen your framework before. Can they understand what it's trying to accomplish? Or do they need to memorize a dozen framework-specific concepts before the code makes sense?

Most modern frameworks fail this test spectacularly. Their templates are filled with cryptic symbols, magical directives, and abstract concepts that have no relationship to the underlying intent. A simple list becomes a mystical incantation that only the initiated can decipher.

Consider this common pattern across different frameworks: You want to show a user's name if they're logged in, and a login button if they're not. This is basic conditional rendering. Something any web developer should be able to understand at a glance.

In many frameworks, this simple intent gets buried under layers of framework-specific syntax. Special directives with obscure names. Conditional operators that work differently than JavaScript. Template languages that require you to think in framework abstractions rather than your actual problem domain.

Aurelia takes a different approach. Our syntax reads like natural language: <div if.bind="user.isLoggedIn">Welcome, ${user.name}!</div>. An experienced web developer can look at this and immediately understand what's happening, even if they've never seen Aurelia before. The intent is clear. The behavior is predictable. The syntax maps directly to the concept.

This isn't an accident. It's the result of obsessive attention to developer experience. We believe that the cognitive load of understanding your framework should be as close to zero as possible. Your mental energy should be devoted to solving business problems, not translating between human intent and framework abstractions.

The benefits of intuitive syntax extend far beyond personal productivity. When your code reads like natural language, it becomes self-documenting. New team members can understand existing code without extensive framework training. Code reviews focus on business logic rather than framework syntax. Bug reports can be understood by non-technical stakeholders.

But intuitive syntax is about more than just readability. It's about predictability. When syntax clearly expresses intent, the behavior becomes obvious. There are no hidden side effects, no mysterious edge cases, no framework magic that changes behavior based on context you can't see.

Consider error handling. In many frameworks, when something goes wrong, the error messages are filled with framework internals. Stack traces point to generated code. Error descriptions use framework jargon that tells you nothing about what actually went wrong in your application.

Aurelia's errors tell you exactly what went wrong and where. When a binding fails, we tell you which property couldn't be found and in which component. When a lifecycle hook throws an exception, we show you the exact method and component that caused the problem. The error messages use the same vocabulary as your code, not our internal implementation details.

This philosophy extends to debugging. When you inspect an Aurelia application in browser dev tools, you see your components, your properties, your methods. The framework doesn't hide behind layers of generated code or proxy objects. What you wrote is what you see. What you debug is what you ship.

The industry has somehow convinced itself that complexity is inevitable. That developer tools must be complicated because the problems they solve are complicated. That you need deep framework knowledge to be productive.

We reject this premise entirely. Complex problems don't require complex tools. They require powerful tools with simple interfaces. The best frameworks make hard things possible and easy things effortless, all while staying out of your way.

When your framework's syntax fights against your natural thinking patterns, every day becomes a translation exercise. You know what you want to accomplish, but you have to constantly convert your intent into framework-specific abstractions. This cognitive overhead accumulates over time, making you slower, more error-prone, and ultimately less satisfied with your work.

Intuitive syntax isn't just about making code easier to write. It's about making development more humane. Your tools should amplify your capabilities, not drain your mental energy. They should feel like natural extensions of your thinking, not obstacles to overcome.

If you can't test it easily, we designed it wrong.

Aurelia's dependency injection system isn't just for organization. It's what makes testing actually pleasant. Need to test a component that depends on services? Just pass in mocks. Everything is classes and interfaces, which means everything is mockable.

No elaborate test setup, no framework gymnastics, no "testing utilities" that are more complex than the code you're testing. Our component lifecycle is predictable and hookable. You can test each phase independently, spy on lifecycle methods, and verify that cleanup happens when it should.

This isn't an accident. We've worked on too many projects where testing was painful, so we made it a first-class concern. If testing something in Aurelia feels hard, that's a bug we want to fix.

We're boring, and proud of it.

Framework churn is a disease. Every six months there's a new paradigm that's going to "revolutionize" web development. Everyone rewrites their applications to chase the shiny new thing. Six months later, that thing is deprecated in favor of the next revolution.

We refuse to participate in this madness.

There are Aurelia applications running in production today that were built in 2015. Nine years later, they still work. The same patterns, the same APIs, the same mental models. The Aurelia of 2015 is, in many fundamental ways, still the Aurelia of today.

This is not an accident. It's a philosophical choice.

While other frameworks have gone through complete rewrites that invalidated entire ecosystems, we've evolved gradually. We've added capabilities without breaking existing ones. We've improved performance without changing programming models.

This makes us unfashionable. Conferences don't invite us to give talks about the revolutionary new paradigm we've invented. Tech Twitter doesn't buzz about our latest rewrite. We don't get to claim we've "solved" web development with our groundbreaking new approach.

Fine by us. Your applications work. Your knowledge compounds instead of becoming obsolete. Your teams stay productive instead of spending months learning the new hotness. That's worth more than being trendy.

Start simple, scale thoughtfully.

The web development industry has a scaling problem, but it's not the one you think. The real problem isn't technical. It's architectural. Most frameworks force you into a false choice: build quick and dirty prototypes that collapse under their own weight, or start with enterprise-grade complexity that crushes productivity from day one.

This is a failure of imagination, not engineering.

Real applications don't start complex. They start simple and become complex over time as requirements evolve, user needs change, and business logic accumulates. The framework you choose should support this natural progression, not fight against it.

Too many frameworks optimize for one end of the spectrum. The trendy ones make demos look effortless but leave you stranded when you need real architecture. The enterprise ones handle massive complexity beautifully but make simple things unnecessarily complicated. You're forced to choose between fast starts and sustainable growth.

Aurelia refuses this false choice. We designed every system to scale gracefully from simple to sophisticated without forcing you to rewrite your mental model or refactor your foundation.

Consider dependency injection. In a small Aurelia application, you might start with simple classes and direct instantiation. As your application grows and testing becomes important, you naturally introduce interfaces and constructor injection. When complexity demands it, you add scoped instances, factory patterns, and custom resolution strategies. Each step builds on the previous one. Your early decisions remain valid even as your architecture evolves.

The component system works the same way. Start with simple, self-contained components that handle their own data and logic. As requirements grow, introduce shared services, component communication patterns, and hierarchical state management. The simple components don't become wrong or need rewriting. They just become part of a larger, more sophisticated system.

Our conventions support this progression naturally. The file-based naming that works for a dozen components still works for hundreds. The lifecycle methods that handle simple initialization also handle complex orchestration. The binding patterns that manage basic data flow scale to handle intricate component interactions.

This isn't theoretical scaling. We've seen applications grow from weekend prototypes to enterprise systems serving millions of users. The fundamental patterns remain consistent. The code written in the early days doesn't become technical debt that needs to be paid down. It becomes the foundation that everything else builds on.

Compare this to frameworks that require architectural rewrites at different scales. Start with simple state management, then throw it away for a "proper" state solution. Begin with basic routing, then replace it with enterprise routing when you need features. Use simple components initially, then refactor everything when you need composition patterns.

This constant rewriting isn't progress. It's waste. It's time spent fighting your tools instead of building features. It's knowledge that expires instead of compounds. It's technical debt disguised as best practices.

We've watched too many projects hit the scaling wall and collapse under their own success. They start fast with a framework that makes demos look effortless. Six months later, they're drowning in unmanageable code, competing patterns, and architectural inconsistencies. The very framework that gave them early velocity becomes the bottleneck that prevents growth.

We've also seen projects start with enterprise-grade complexity from day one. Multiple abstraction layers, sophisticated patterns, elaborate architectures. Six months later, they're still building infrastructure instead of features. The complexity that was supposed to enable scale becomes the burden that prevents delivery.

Aurelia's approach is different. The patterns that work for small applications are the same patterns that work for large applications, just applied at different scales. Dependency injection scales from simple constructor parameters to complex service hierarchies. Component composition scales from basic parent-child relationships to sophisticated architectural patterns. Convention-based structure scales from individual files to team-based module organization.

This consistency has profound implications for team productivity. New developers don't need to learn different patterns as the application grows. Senior developers don't need to constantly re-architect as requirements evolve. The mental model that serves you well early in the project continues serving you well as the project matures.

Your testing strategies scale the same way. The mocking patterns that work for simple components work for complex service interactions. The lifecycle testing that validates basic behavior also validates sophisticated orchestration. The integration tests that cover simple workflows extend naturally to cover complex business processes.

Your debugging experience remains consistent as complexity grows. The error messages that help you understand simple binding issues also help you understand complex dependency resolution problems. The development tools that illuminate basic component behavior continue working as your component hierarchies become more sophisticated.

The industry has convinced itself that scaling requires fundamental architectural changes. That simple patterns must be abandoned for complex ones. That early code must be rewritten for production use.

We believe that well-designed simple patterns naturally evolve into well-designed complex patterns. That the best foundation for a large application is a small application that grew thoughtfully. That architectural consistency across scales is more valuable than perfect optimization at any individual scale.

When you build with Aurelia, you're not just building an application. You're growing an architecture. The decisions you make early don't constrain your future options. They create a foundation that supports whatever your application becomes.

Start simple. Scale thoughtfully. Never rewrite your foundation. That's how real applications get built.

We don't chase GitHub stars. We chase solutions.

Let's be honest about where we stand. We're not the popular choice. We don't have billion-dollar tech giants throwing marketing budgets at us. We don't have armies of developer advocates making conference circuit rounds. We don't have influencers creating viral videos about the Aurelia revolution.

React has more GitHub stars than we'll ever see. Vue gets more downloads in a day than we get in a month. Angular dominates job postings and Stack Overflow questions.

And we're completely fine with that.

Popularity is a lagging indicator, not a leading one. It tells you what was trendy yesterday, not what will solve your problems tomorrow. The most popular framework isn't necessarily the best framework for your specific needs. It's just the one with the most mindshare at this particular moment.

We've been around long enough to watch the cycles. Technologies rise and fall based on hype as much as merit. Yesterday's revolutionary breakthrough becomes tomorrow's legacy system. The graveyard of web development is full of frameworks that were once the absolute hottest thing in tech.

While the popular frameworks optimize for conference buzz and Twitter engagement, we optimize for applications that work reliably over years, not months. We worry about whether our abstractions will make sense to your team three years from now, not whether they'll trend on Hacker News next week.

The tech industry loves its popularity contests. Industry analysts write reports about the "big three" and mention us as a footnote, if at all. Bootcamps teach the frameworks that help graduates get hired fastest, not necessarily the ones that will serve them best in the long run.

That's the game, and we understand it. But we're playing a different game entirely.

We're optimizing for developers who value substance over signals. For teams who care more about shipping reliable software than using the latest hotness. For organizations who measure success by user satisfaction, not developer satisfaction surveys.

The core team doesn't maintain Aurelia as a side project or resume builder. We stake our professional reputations on it. We bet our careers on it. We build production applications with it every day. When we make a design mistake, we live with it in our own codebases. When we get something right, we benefit directly. Our incentives are perfectly aligned with yours.

Being the unpopular choice gives us something invaluable: complete intellectual freedom. We don't have to pretend every new JavaScript trend is revolutionary. We don't have to generate artificial excitement to satisfy venture capitalists. We don't have to compromise our engineering principles to chase market share.

We can afford to be boring when boring is more reliable. We can afford to be unfashionable when unfashionable is more sustainable. We can afford to be right instead of popular.

The frameworks that are popular today won't necessarily be popular tomorrow. There will be new paradigms, new solutions, new ways of thinking about web development. The cycle will continue, as it always has.

But the applications built with Aurelia will keep running. The teams using Aurelia will keep shipping. The problems solved with Aurelia will stay solved.

Because quality outlasts popularity. Substance outlasts hype. Reliability outlasts trendiness.

We're not trying to win a popularity contest. We're trying to build the most thoughtful, sustainable, and useful framework we can. For developers and teams who share those values.

That's exactly the position we want to be in.

No training wheels, no safety scissors.

Most frameworks treat you like you can't be trusted with real power. They give you a carefully curated set of approved patterns and lock everything else behind "here be dragons" warnings. They make architectural decisions for you and provide no way to change them. They assume you'll hurt yourself if given too much control.

We think that's insulting to your intelligence.

Aurelia is designed around a radical premise: you know what you're doing. You understand your requirements better than we do. You should have the power to make your own architectural decisions, even if we wouldn't make the same ones.

Don't like our default binding syntax? Configure it. Want custom template behaviors? Build them. Need different binding modes? Create them. The templating and binding systems are designed for extensibility at every level.

This isn't theoretical power. It's real, practical extensibility that teams use in production applications. We've seen developers create custom binding behaviors that handle complex scenarios we never anticipated. We've seen teams build specialized value converters that transform data in domain-specific ways. We've seen companies extend the templating system with custom attributes that encapsulate their business logic.

But here's the beautiful part: you don't need any of this complexity to get started. Aurelia works perfectly out of the box without any configuration. Most teams never need to replace a single component. The power is there when you need it, invisible when you don't.

Compare this to frameworks that make you choose between "simple but limited" and "powerful but complex." We give you simple AND powerful. The default experience just works. The advanced capabilities are there when your requirements demand them.

Need direct DOM access? Take it. The framework won't fight you or wrap everything in virtual abstractions. Need to hook into the component lifecycle at a granular level? Every lifecycle method is available and predictable. Need to customize how dependency injection works? The entire container is configurable.

Want to integrate a third-party library that expects to own part of the DOM? Go ahead. Aurelia won't interfere with your jQuery plugins, your D3 visualizations, or your WebGL canvases. We give you escape hatches everywhere because we know real applications have messy requirements.

Our dependency injection system exemplifies this philosophy. Out of the box, it handles constructor injection with sensible defaults. But if you need custom resolution strategies, scoped instances, factory functions, or completely custom behaviors, the system is flexible enough to handle it all.

The templating system works the same way. The default syntax handles 95% of use cases elegantly. But when you need custom binding behaviors, specialized value converters, or completely novel template constructs, the architecture supports it without forcing you to fight the framework.

Yes, this means you can hurt yourself. You can create circular dependencies that crash at runtime. You can bind to expensive computations that tank performance. You can write components that leak memory all over the place. You can architect systems that are impossible to maintain.

We're not going to stop you. We're also not going to assume you're incompetent enough to do these things accidentally.

The industry trend is toward frameworks that make dangerous things impossible. Every API is locked down. Every extension point is carefully controlled. Every architectural decision is made for you "for your own good."

We prefer frameworks that make powerful things possible. We trust you to understand the trade-offs. We trust you to test your code. We trust you to make responsible decisions about performance and maintainability.

This philosophy extends to our error handling. When something goes wrong, we don't hide it behind friendly abstractions. We show you exactly what failed, where it failed, and why it failed. Our error messages assume you're capable of understanding technical details and fixing the underlying problem.

Other frameworks optimize for protecting developers from themselves. We optimize for empowering developers to solve their problems. Sometimes those problems require sharp tools, direct access, and the freedom to make unconventional choices.

The difference is trust. We trust that you're a professional who can handle professional tools. We trust that you'll read the documentation, understand the implications, and make informed decisions about your architecture.

When you need to do something unusual, something the framework designers never anticipated, you shouldn't have to fight your tools or work around artificial limitations. You should be able to extend, customize, and override as needed.

That's what real power looks like. Not just the ability to configure options, but the ability to fundamentally change how the framework behaves when your requirements demand it.

The training wheels come off. The safety scissors get put away. We hand you the real tools and trust you to build something amazing.

Everything works together because we designed it that way.

Modern web development has become an exercise in integration hell. Install seventeen npm packages with incompatible APIs. Configure twenty-three build tools that don't know about each other. Wire together forty-nine loosely related libraries that were never designed to work as a system. Then spend three days debugging version conflicts, peer dependency warnings, and mysterious build failures.

This is insanity disguised as flexibility.

The JavaScript ecosystem's obsession with modularity has created a paradox: in trying to make everything composable, we've made nothing actually compose well. Every package is an island. Every library has its own conventions, its own configuration format, its own way of handling errors. Integrating them requires endless glue code, adapter layers, and configuration files that exist solely to make incompatible things pretend to work together.

Aurelia takes a radically different approach. We're a complete system designed as a complete system from day one.

Our router doesn't just handle navigation. It understands our component lifecycle, integrates with our dependency injection system, and works seamlessly with our templating engine. When you navigate to a route, the router knows how to instantiate components with their dependencies, bind their properties, and manage their lifecycle hooks. No adapters, no glue code, no configuration mapping.

Our templating system doesn't exist in isolation. It's deeply integrated with our binding engine, our component system, and our validation framework. When you bind to a property in a template, the system understands the component's lifecycle, respects the validation rules, and integrates with the change detection system. Everything flows together naturally.

Our testing utilities aren't afterthoughts built by the community. They're designed specifically for Aurelia's architecture. They understand our dependency injection system, so mocking is trivial. They know our component lifecycle, so testing different phases is straightforward. They integrate with our templating system, so testing complex UI interactions doesn't require elaborate setup.

This integration goes deeper than just APIs that work well together. Our error messages are consistent across all systems because they're built by the same team with the same philosophy. Our debugging experience is coherent because all the pieces understand each other. Our performance optimizations work across the entire stack because we control the entire stack.

Compare this to the typical modern web application. You have a routing library that knows nothing about your state management solution. A component framework that's unaware of your validation library. A testing framework that requires custom adapters to work with your template syntax. Each piece is excellent in isolation, but together they create a fragmented experience.

When something goes wrong in a cobbled-together system, good luck figuring out where. Is it the router? The state manager? The component library? The build tool? The integration layer between two of them? You'll spend more time debugging the interactions between your tools than the actual business logic they're supposed to support.

When something goes wrong in Aurelia, the error messages tell you exactly what happened and where. The stack traces point to your code, not framework internals or integration adapters. The debugging experience is consistent because there's one coherent system, not a collection of independent libraries pretending to be friends.

This approach has real costs. We can't always use the "best of breed" solution for every individual piece. Our router might not have every feature of the most advanced standalone routing library. Our state management might not be as sophisticated as the latest state management trend. We have to build and maintain more code instead of delegating to the community.

But the benefits are transformative. You spend your time building features, not integrating tools. You debug your application logic, not framework compatibility issues. You learn one coherent system instead of a dozen different libraries with conflicting philosophies.

Your team onboards faster because there's one consistent way of doing things across the entire application. Your application performs better because all the pieces are optimized to work together. Your codebase is more maintainable because there are fewer integration layers and compatibility shims.

When you need to add a new feature, you're working with the framework, not against a collection of competing libraries. When you need to debug a problem, you're working within one system with consistent patterns, not trying to understand the interaction between multiple independent systems.

The industry has convinced itself that maximum modularity leads to maximum flexibility. That the best system is one assembled from the best individual components. That integration is someone else's problem.

We believe integration is the most important problem. That a complete system designed to work together will always be more reliable than a collection of perfect pieces that weren't designed for each other.

We built Aurelia as a complete, integrated solution because that's what real applications need. Not maximum theoretical flexibility, but maximum practical reliability. Not the coolest individual components, but the most coherent overall experience.

You don't have to become an expert in seventeen different libraries just to build a web application. You don't have to spend weeks researching compatibility matrices and integration guides. You don't have to maintain a tower of adapters and glue code that adds complexity without adding value.

You just build your application. The framework handles the rest.

What you see is what you get.

Framework magic is a disease. Hidden behaviors, implicit conventions that change based on context, APIs that behave differently depending on what phase of the moon it is. Too many frameworks treat mystery as a feature.

Aurelia is boringly predictable.

When you bind to a property, it binds to that property. When you trigger an event, it triggers that event. When you inject a dependency, you get that dependency. The behavior you see is the behavior you get.

Our error messages tell you exactly what went wrong and how to fix it. Our lifecycle hooks run in the order you'd expect. Our binding system does what the syntax suggests it does.

This predictability isn't an accident. It's a core design principle. Complex applications require dependable foundations. When your framework behaves surprisingly, everything built on top of it becomes fragile.

Boring reliability beats clever unpredictability every time.

We improve by addition, not destruction.

The tech industry is obsessed with dramatic rewrites. Every few years, someone declares that everything we've learned is wrong and we need to start over from scratch. New paradigms emerge that invalidate entire ecosystems. Frameworks abandon their users in pursuit of architectural purity.

This is progress theater, not actual progress.

Real progress preserves what works while improving what doesn't. It builds on existing knowledge instead of discarding it. It respects the investments people have made in learning your platform, building their applications, and training their teams.

Too many frameworks treat major versions like clean slates. They change fundamental concepts, abandon proven patterns, and force you to relearn everything. The justification is always the same: "We had to break things to make them better."

We believe progress and stability aren't opposites. They're requirements that must be balanced.

Consider how we approached Aurelia 2. We rebuilt the framework's internals for dramatically better performance. We redesigned the binding system for more predictable behavior. We modernized the architecture to support emerging web standards. We fixed years of accumulated design debt.

But we didn't throw away what worked.

If you know how to build an Aurelia 1 application, you know how to build an Aurelia 2 application. The same conventions work. The same mental models apply. The same patterns scale. Your components are still classes with lifecycle methods. Your templates still use the same binding syntax. Your dependency injection still works the same way.

We made the performance improvements invisible to your application code. We enhanced the binding system without changing its behavior from your perspective. We modernized the architecture while preserving the programming model you'd learned.

Yes, some things changed. Some APIs became more consistent. Some edge cases were fixed. Some deprecated features were finally removed. But the core experience of building with Aurelia remained fundamentally the same.

This approach has costs. We couldn't make radical performance improvements that would have required completely different programming models. We couldn't chase architectural trends that would have invalidated existing knowledge. We had to think carefully about every change because we knew people were depending on the current behavior.

But this approach also has benefits. Your Aurelia 1 knowledge transferred directly to Aurelia 2. Your team didn't need months of retraining. Your migration path was evolutionary, not revolutionary. Your investment in the platform continued paying dividends.

When other frameworks release major versions, teams often decide it's easier to rewrite their applications than migrate them. When we released Aurelia 2, teams migrated because it was the obvious next step, not a leap into the unknown.

Progress without preservation is just churn. We choose sustainable progress over revolutionary change because we're building for the long term. Your applications deserve better than constant rewrites. Your teams deserve better than endless relearning. Your users deserve better than instability disguised as innovation.

These aren't just marketing principles. They're the beliefs that shaped every architectural decision, every API design, and every line of documentation. When you choose Aurelia, you're choosing more than a framework. You're choosing an approach to web development that values your time, respects your intelligence, and bets on the long-term health of the web platform.

Whether you're building your first application or your hundredth, whether you're working solo or on a team of dozens, whether you're prototyping or preparing for production, Aurelia is designed to meet you where you are and grow with you where you're going.

This is why we build.

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.

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.

In addition to binding single classes conditionally, you can also bind multiple classes based on a single boolean expression using a comma-separated list in the .class binding syntax. This allows you to toggle a set of related classes together.

In this example, if the hasError property in your view model is truthy, all four classes (alert, alert-danger, fade-in, and bold-text) will be added to the div element. If hasError is falsy, all four classes will be removed. Important Note: When using the comma-separated syntax for multiple classes, ensure there are no spaces around the commas. The parser expects a direct list of class names separated only by commas (e.g., class1,class2,class3).

Besides the .class syntax, there are other ways to achieve dynamic class binding, especially when dealing with complex logic or generating class strings:

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

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

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:

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.

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?

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.

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.

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.

Use this section as your orientation to Aurelia. Each topic builds on the last, moving from first render through composition patterns, state management, and the services that power real applications.

How to Navigate

• Start with the introductions to see Aurelia's templating flavor and ergonomics in action.

• Pick the boot path (full app vs. enhancement) that matches your project.

• Add capabilities incrementally: routing, composition, observation, without waiting for a rewrite.

• Dip into advanced topics last, once the fundamentals are comfortable.

1. Skim the templating introductions to get comfortable with Aurelia's binding language.

2. Choose your startup approach: full SPA bootstrap or incremental enhancement.

3. Layer on routing once you have more than one screen.

Each article calls out prerequisites and links forward so you can keep learning without losing the big picture.

Aurelia 2 allows you to manage 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.

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

• <let>

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.

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

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

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

This topic demonstrates how to work with Aurelia's built-in template commands which allow you to conditionally show and hide content, loop over collections of content, conditional rendering using switch/case syntax in your views and a trove of other built-in template features.

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

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

In the following example, we are passing a value called isLoading

Optional step: This adds route data for role requirements and enforces it with a router hook. You will also add a small auth status widget to toggle the admin role in the UI. If you want to keep the tutorial beginner-friendly, you can stop after Step 5.

1. Create a tiny auth service

Create src/services/auth-service.ts:

import { DI } from '@aurelia/kernel';

export type User = {
  name: string;
  roles: string[];
};

export const IAuthService = DI.createInterface<IAuthService>(
  'IAuthService',
  x => x.singleton(AuthService)
);

export interface IAuthService extends AuthService {}

export class AuthService {
  private user: User | null = { name: 'Taylor', roles: ['member'] };

  getCurrentUser(): User | null {
    return this.user;
  }

  hasRole(role: string): boolean {
    return !!this.user?.roles.includes(role);
  }

  toggleRole(role: string): void {
    if (!this.user) return;

    if (this.user.roles.includes(role)) {
      this.user = { ...this.user, roles: this.user.roles.filter(item => item !== role) };
      return;
    }

    this.user = { ...this.user, roles: [...this.user.roles, role] };
  }
}

2. Create a role-based router hook

Create src/role-hook.ts:

import { resolve } from '@aurelia/kernel';
import { lifecycleHooks } from '@aurelia/runtime-html';
import { IRouteViewModel, Params, RouteNode } from '@aurelia/router';
import { IAuthService } from './services/auth-service';

@lifecycleHooks()
export class RoleHook {
  private readonly auth = resolve(IAuthService);

  canLoad(_viewModel: IRouteViewModel, _params: Params, next: RouteNode): boolean | string {
    const requiredRoles = next.data?.roles as string[] | undefined;
    const fallbackRoute = (next.data?.fallbackRoute as string | undefined) ?? 'forbidden';

    if (!requiredRoles || requiredRoles.length === 0) {
      return true;
    }

    const hasRequiredRole = requiredRoles.some(role => this.auth.hasRole(role));
    return hasRequiredRole ? true : fallbackRoute;
  }
}

Register the hook in src/main.ts:

import Aurelia from 'aurelia';
import { RouterConfiguration } from '@aurelia/router';
import { MyApp } from './my-app';
import { RoleHook } from './role-hook';

Aurelia
  .register(
    RouterConfiguration.customize({ activeClass: 'is-active' }),
    RoleHook
  )
  .app(MyApp)
  .start();

3. Add protected routes with route data

Create src/pages/admin-page.ts:

Create src/pages/admin-page.html:

Create src/pages/forbidden-page.ts:

Create src/pages/forbidden-page.html:

Update src/my-app.ts to add route data:

Create src/components/auth-status.ts:

Create src/components/auth-status.html:

Update src/pages/dashboard-page.html to show it:

Finally, add the Admin link in src/my-app.html:

• Route data carries the roles requirement.

• The RoleHook reads next.data and redirects to forbidden if roles are missing.

Back to:

Learn how to handle file inputs and uploads in Aurelia forms.

Basic File Input

<form>
  <label for="fileUpload">Select files to upload:</label>
  <input
    id="fileUpload"
    type="file"
    multiple
    accept="image/*"
    change.trigger="handleFileSelect($event)" />

  <button
    click.trigger="uploadFiles()"
    disabled.bind="!selectedFiles.length">
    Upload
  </button>
</form>

export class FileUploadComponent {
  selectedFiles: File[] = [];

  handleFileSelect(event: Event) {
    const input = event.target as HTMLInputElement;
    if (!input.files?.length) return;

    this.selectedFiles = Array.from(input.files);
  }

  async uploadFiles() {
    if (this.selectedFiles.length === 0) return;

    const formData = new FormData();
    for (const file of this.selectedFiles) {
      formData.append('files', file, file.name);
    }

    try {
      const response = await fetch('/api/upload', {
        method: 'POST',
        body: formData
      });

      if (!response.ok) {
        throw new Error(`Upload failed with status ${response.status}`);
      }

      const result = await response.json();
      console.log('Upload successful:', result);
      this.selectedFiles = [];
    } catch (error) {
      console.error('Error uploading files:', error);
    }
  }
}

Single File Upload

<input type="file" accept="image/*" change.trigger="handleFileSelect($event)" />

handleFileSelect(event: Event) {
  const input = event.target as HTMLInputElement;
  this.selectedFiles = input.files?.length ? [input.files[0]] : [];
}

File Preview

export class FilePreviewComponent {
  selectedFile: File | null = null;
  previewUrl: string | null = null;

  handleFileSelect(event: Event) {
    const input = event.target as HTMLInputElement;
    const file = input.files?.[0];

    if (file) {
      this.selectedFile = file;
      this.createPreview(file);
    }
  }

  private createPreview(file: File) {
    if (this.previewUrl) {
      URL.revokeObjectURL(this.previewUrl);
    }

    this.previewUrl = URL.createObjectURL(file);
  }

  detaching() {
    if (this.previewUrl) {
      URL.revokeObjectURL(this.previewUrl);
    }
  }
}

<input type="file" accept="image/*" change.trigger="handleFileSelect($event)" />

<div if.bind="previewUrl" class="preview">
  <img src.bind="previewUrl" alt="Preview" />
  <p>${selectedFile.name} (${(selectedFile.size / 1024).toFixed(2)} KB)</p>
</div>

Validation

export class ValidatedFileUpload {
  selectedFile: File | null = null;
  error: string | null = null;

  maxSize = 5 * 1024 * 1024; // 5MB
  allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];

  handleFileSelect(event: Event) {
    this.error = null;
    const input = event.target as HTMLInputElement;
    const file = input.files?.[0];

    if (!file) return;

    if (!this.allowedTypes.includes(file.type)) {
      this.error = 'Only JPEG, PNG, and GIF images are allowed';
      input.value = '';
      return;
    }

    if (file.size > this.maxSize) {
      this.error = `File size must be less than ${this.maxSize / (1024 * 1024)}MB`;
      input.value = '';
      return;
    }

    this.selectedFile = file;
  }
}

Progress Tracking

export class FileUploadWithProgress {
  uploadProgress = 0;
  isUploading = false;

  async uploadWithProgress(file: File) {
    this.isUploading = true;
    this.uploadProgress = 0;

    const xhr = new XMLHttpRequest();

    return new Promise((resolve, reject) => {
      xhr.upload.addEventListener('progress', (e) => {
        if (e.lengthComputable) {
          this.uploadProgress = (e.loaded / e.total) * 100;
        }
      });

      xhr.addEventListener('load', () => {
        this.isUploading = false;
        if (xhr.status >= 200 && xhr.status < 300) {
          resolve(JSON.parse(xhr.responseText));
        } else {
          reject(new Error(`Upload failed: ${xhr.status}`));
        }
      });

      xhr.addEventListener('error', () => {
        this.isUploading = false;
        reject(new Error('Upload failed'));
      });

      const formData = new FormData();
      formData.append('file', file);

      xhr.open('POST', '/api/upload');
      xhr.send(formData);
    });
  }
}

<input type="file" change.trigger="handleFileSelect($event)" />

<div if.bind="isUploading" class="progress">
  <div class="progress-bar" css="width: ${uploadProgress}%"></div>
  <span>${uploadProgress.toFixed(0)}%</span>
</div>

Best Practices

1. Validate on both client and server - Always verify file types and sizes server-side

2. Clean up object URLs - Revoke object URLs in detaching() to prevent memory leaks

3. Show progress for large files - Use XMLHttpRequest for progress tracking

4. Provide clear feedback - Show file names, sizes, and upload status

5. Handle errors gracefully - Display meaningful error messages

• Validate file types server-side (don't trust accept attribute)

• Check file sizes to prevent DoS attacks

• Scan uploaded files for malware

Aurelia's primary router gives you a declarative, component-first navigation system with strong type safety, multi-viewport layouts, and deep integration with dependency injection. If you have used Angular's router or the classic Aurelia 1 router, the mental model will feel familiar: define a route table, map URLs to components, nest layouts, guard navigation, lazy-load feature areas, and respond to lifecycle events. The Aurelia router stays HTML-friendly and convention-driven, letting you compose navigation without wrapper modules or excessive configuration.

Still deciding between routers? Start with Choosing the right Aurelia router.

Highlights

• Structured route tree lets you describe nested layouts, auxiliary viewports, and fallback routes in one place while still co-locating child routes with their components via @route.

• Viewport-first layouts allow flexible page composition: declare multiple <au-viewport> elements, name them, and target them from route definitions. This makes responsive shells and split views straightforward.

• Lifecycle hooks and events mirror the intent of Angular guards (canLoad, canActivate, etc.) while using Aurelia conventions (canLoad, loading, canUnload, unloading). Hooks execute in well-defined order and support async work.

• Navigation state management gives you centralized insight into route activation, title building, and analytics hooks, ideal for larger apps.

• Progressive enhancement via the load and href attributes keeps markup readable and usable even before hydration.