Introduction
Aurelia is a frontend JavaScript framework that is simple, powerful and unobtrusive. It stays out of your way with a plain binding & observation system and an intuitive, expressive & extensible templating system. Let's dive into Aurelia via hundred of examples.
Hello world
A basic example of Aurelia template. Hello world!
xxxxxxxxxx<h1>${message}</h1>xxxxxxxxxxexport class App { message = "Hello world!";}Displaying text
Using Aurelia's interpolation syntax (a dollar sign followed by enclosed curly braces) ${} to display text in your views. By default, Aurelia is also taught to use textcontent.bind or textcontent="${property}" to display text:
Displaying html
Use innerhtml.bind for when you want to update element.innerHTML. HTML nodes & elements are also supported, with the caveat that they will be appended as is, which means one value cannot be used in multiple locations.
Setting attribute
By default, "aria-", "data-", "class", "styles" and standard svg attributes are treated as attribute, instead of properties.
Setting classes
Interpolation and ".class" binding command can be used to set a class on an element
Setting styles
Interpolation and ".style" binding command can be used to set one or many styles on an element
Rendering collections
In most applications, your model is not only composed of objects, but also of various types of collections. Aurelia provides a robust way to handle collection data through its built-in "repeat" attribute. Repeaters can be used on any element, including custom elements and template elements too!
Rendering array
Render each item of an array via repeat.for
Rendering Set
Render each item of a set via repeat.for
Rendering Map
Render each item of a map via repeat.for
Rendering a range
Iterate from 0 to a given number to render, via repeat.for
Rendering object key/value pairs
Objects are not iterable, though if piped through a value converter, it's possible to use repeat.for
Contextual properties
There are contextual properties inside a repeat for: - $index: (number) the current item index - $length: (number) the length/size of the collection - $first: (boolean) true if the current item is the first in the collection - $last: (boolean) true if the current item is the last in the collection - $middle: (boolean) true if the current item is neither first nor last in the collection - $even: (boolean) true if the current item index is even - $odd: (boolean) true if the current item index is odd
Nested collection rendering
Aurelia supports nested collection rendering intuitively. Parent scope of a repeat scope can be accessed via "$parent".
Handling events
Aurelia makes it easy for you to handle standard/custom DOM event.
Basic of event handling
Aurelia's binding system supports binding to standard and custom DOM events. A DOM event binding will execute a JavaScript expression whenever the specified DOM event occurs. Event binding declarations have three parts and take the form event.command="expression". - event: This is the name of a DOM event, without the "on" prefix, just as you would pass to the native addEventListener() API. e.g. "click" - command: One of the following event binging commands: - trigger: Attaches an event handler directly to the element. When the event fires, the expression will be invoked. - capture: Attaches a single event handler to the element in capturing phase. - delegate: Attaches a single event handler to the document (or nearest shadow DOM boundary) which handles all events of the specified type in bubbling phase, properly dispatching them back to their original targets for invocation of the associated expression. - expression: A JavaScript expression. Use the special $event property to access the DOM event in your binding expression.
Self binding behavior
Sometimes it is desirable to fire an event if the origin of the event is the element the event listener is attached to. Aurelia supports this via "Self" binding behavior, syntax: "& self"
Conditional rendering
Change what is rendered or shown based on conditions in your code.
With show/hide
An example of conditional rendering syntaxes in Aurelia with show/hide. Using this when it is desirable to hide/show an element without removing it from the document.
With if/else
Examples of conditional rendering syntaxes in Aurelia with if/else.Using this when it is desirable to remove the elements when the condition is false/falsy
With switch
Examples of conditional rendering syntaxes in Aurelia with switch/case/default.Using this when it is desirable to have the semantic of switch syntax
With promise
Examples of conditional rendering syntaxes in Aurelia with promise/pending/then/catch.Using this when it is desirable to have the semantic of Promise in JavaScript, without intermediate view model code
Form text input
It is not uncommon that at some point, your application will contain some form elements that provide the ability to allow user input. Whether they be select dropdowns, text inputs or buttons, Aurelia makes working with forms intuitive.
Input text
A common element seen in forms is text <input>. Aurelia supports this via "value.bind"
Input number
Two way binding with a number <input/>, as string
Input number + value converter
Two way binding with a number <input/>, with the help of "| number" value converter expression to turn string into number
Input number + valueAsNumber
Two way binding with number <input/>, via "valueAsNumber" property, to reduce boiler plate converting string to number
Textarea
A textarea element is just like any other form element. It allows you to bind to its value and by default "value.bind" will be two-way binding (meaning changes in the view will flow to the view-model, and changes in the view-model will flow to the view).
Form checkboxes
Aurelia supports two-way binding a variety of data-types to checkbox input elements..
Checkbox + booleans
Bind a boolean property to an input element's checked attribute using checked.bind="myBooleanProperty"
Checkbox + number array
A set of checkbox elements is a multiple selection interface. If you have an array that serves as the "selected items" list, you can bind the array to each input's checked attribute. The binding system will track the input's checked status, adding the input's value to the array when the input is checked and removing the input's value from the array when the input is unchecked
Checkbox + object array
Numbers aren't the only type of value you can store in a "selected items" array. The binding system supports all types, including objects. Here's an example that adds and removes "product" objects from a "selectedProducts" array using the checkbox data-binding.
Checkbox + objects array + matcher
You may run into situations where the object your input element's model is bound to does not have reference equality to any of the objects in your checked array. The objects might match by id, but they may not be the same object instance. To support this scenario you can override Aurelia's default "matcher" which is a equality comparison function that looks like this: (a, b) => a === b. You can substitute a function of your choosing that has the right logic to compare your objects.
Checkbox + string array
An example that adds and removes strings from a selectedProducts array using the checkbox data-binding. In this is, standard checkbox value attribute is used.
Form radios
A group of radio inputs is a type of "single select" interface. Aurelia supports two-way binding any type of property to a group of radio inputs. The examples below illustrate binding number, object, string and boolean properties to sets of radio inputs. In each of the examples there's a common set of steps: 1. Group the radios via the `name` property. Radio buttons that have the same value for the name attribute are in the same "radio button group"; only one radio button in a group can be selected at a time. 2. Define each radio's value using the `model` property. 3. Two-way bind each radio's `checked` attribute to a "selected item" property on the view-model.
Radios + numbers
In this example each radio input will be assigned a number value via the model property. Selecting a radio will cause its model value to be assigned to the "selectedProductId" property.
Radios + objects
The binding system supports binding all types to radios, including objects. Here's an example that binds a group of radios to a selectedProduct object property.
Radios + objects + matcher
You may run into situations where the objects in your view and view model may look the same, but are different objects. To support this scenario you can override Aurelia's default "matcher", which looks like this: (a, b) => a === b.
Radios + booleans
In this example each radio input is assigned one of three literal values: null, true and false. Selecting one of the radios will assign its value to the likesCake property.
Radios + strings
Aurelia also knows how to deal with standard value attribute of radio input. An example is as follow
Form selects
A <select> element can serve as a single-select or multiple-select "picker" depending on whether the multiple attribute is present. The binding system supports both use cases. The samples below demonstrate a variety scenarios, all use a common series of steps to configure the select element: 1. Add a <select> element to the template and decide whether the multiple attribute should be applied. 2. Bind the select element's value attribute to a property. In "multiple" mode, the property should be an array. In singular mode it can be any type. 3. Define the select element's <option> elements. You can use the repeat or add each option element manually. 4. Specify each option's value via the model property: <option model.bind="product.id">${product.name}</option> You can use the standard value attribute instead of model, just remember- it will coerce anything it's assigned to a string.
Select + numbers
Binding a number from select options with the view model is done via value.bind on the <select>, and model.bind on the <option>
Select + objects
Binding an object from select options with the view model is done via value.bind on the <select>, and model.bind on the <option>
Select + objects + matcher
You may run into situations where the objects in your view and view model may look the same, but are different objects. To support this scenario you can override Aurelia's default "matcher", which looks like this: (a, b) => a === b.
Select + booleans
Binding a boolean value from select options with the view model is done via value.bind on the <select>, and model.bind on the <option>
Select + strings
Unlike other kinds of value above, string works natively with the value property of <option>. Example is as following:
Select + multiple + numbers
Aurelia also knows how to handle multiple attribute on the <select>, as intuitive as the usage without it. To bind with a multi select, use an array. Following is an example how to bind multi number select:
Select + multiple + objects
Aurelia also knows how to handle multiple attribute on the <select>, as intuitive as the usage without it. To bind with a multi select, use an array and ensure model.bind is used on the <option> Following is an example how to bind multi object select:
Select + multiple + strings
Multi select binding with strings are simpler than other form, as option value works natively with string.Following is an example how to bind multi string select:
Form submission
Submitting a form
It is recommended to use standard way to submit a form, via a submit control, typically a button without a type, or type="submit"
Submission handling
Hook into the submission event of a form using standard submit event
Retrieving references
Retrieve the reference to an element, a custom element or custom attribute view model via ref, view-model.ref or (attr-name).ref.
Element reference
Use "ref" attribute on an element to express the property to assign the element reference to. The value will be available after "binding" lifecycle, and before "bound" lifecycle
Custom element VM reference
Use "view-model.ref" on a custom element to express the property to assign the element view model reference to. The value will be available after "binding" lifecycle, and before "bound" lifecycle
Custom attribute VM reference
Use "xxxx.ref", where xxxx is the name of the attribute, on a custom element to express the property to assign a custom attribute view model reference to. The value will be available after "binding" lifecycle, and before "bound" lifecycle
Date picker
A common UI component seen in many applications. There are many ways to build/handle such requirements
Native date picker
An exmaple of how to bind HTML native datepicker with Aurelia
Native date picker + converter
It is sometimes desirable to retrieve a date object out of a dateinput. An exmaple of how to bind HTML native datepicker with Aurelia, with a value converter
Pikaday
A simple example using a thirdparty datepicker component: Pikaday
Flatpickr
A simple example using a thirdparty datepicker component: Flatpickr
Focus/Blur binding
Controlling and getting notified when an element receives focus is a common task in many applications. Aurelia helps application manage this with ease.
Focus tracking via event
An plain way to track scroll position of a scroller is via "focus" event.
Focus tracking via binding
Aurelia also provides two way binding for focus tracking, use "focus.bind" to achieve this
Focus binding with input
An example of a common task: binding the focus of an <input> with a property
Blur tracking via event
Sometimes it is desirable to know whether an element has lost focus, a plain way to do this is via "blur" event with "blur.trigger"
Scroll position binding
A common need in application is scroll position tracking. Aurelia supports this via 2 ways: event and direct binding.
Scroll tracking via event
An plain way to track scroll position of a scroller is via "scroll" event.
Scroll tracking via binding
Aurelia is taught to handle scroll binding, supporting two way binding with scroll position with intuitiveness.
Dynamic binding scope
Excessive boilerplate could comes up when binding with long property paths. Aurelia helps manage this easier with "with", like JavaScript "with" syntax
With + static scope
A simple way to have different scope for bindings inside a view
With + dynamic scope
Most of the time, applications will need to switch between different objects as scope for bindings of a part of the template. "with" supports the the dynamic assignment of scope to help handle this with ease.
Declarative computed with <let/>
Aurelia provides a way to declare computed value in HTML with <let/> element, to enhance compactness & expressiveness of templates.
Let basic
A simple way to declare view-only computed value
Let on binding context
A way to declare computed value in the binding context from the view
Portalling elements
There are situations that some elements of a custom element should be rendered at a different location within the document, usually at the bottom of a document body. Aurelia supports this intuitively with [portal] custom attribute.
Portal basic
Move an element to under the document body, while maintaining the binding context
Portal + CSS selector
Using target binding on the portal attribute, moving elements to different destination using CSS selector is a breeze.
Portal + element reference
Portal also supports element reference as target, beside CSS selectors, making it flexible in many scenarios.
Advanced examples
Above are the basic examples of what Aurelia could do, and how Aurelia could help you handle common scenarios met in an application. The examples below will delve into more advanced scenarios to help you combine various concepts & features to create more sophisticated applications, while still keeping everything manageable and enjoyable 😃.