Get the Newsletter

Aurelia Release Notes - March 2020

Posted by Rob Eisenberg on March 3, 2020

This month we've got major releases of aurelia-i18n, aurelia-dialog, and aurelia-pal-nodejs. However, the most significant release is a minor release of Aurelia UX, which includes many improvements to the components and styles.

Major Releases

Major updates may include breaking changes, new features, fixes to bugs, and performance improvements.

aurelia-i18n 3.0.0

Breaking Changes

  • t-attribute: undefined and null bound values ( #314 ) ( 2a61ee7 )

Note that if the keyExpr in t="keyExpr" or t.bind="keyExpression" is evaluated to be null, undefined, or 0, the translation will now fallback to an empty string. This is different than the previous behavior in the sense that previously the original content was preserved.

What does this mean?

Scenario#1: The key expression is changed to null, undefined, or 0.

Previously the old content was left untouched.

  <span t.bind="key.expr"><span> <!-- assuming key.expr is a valid string value the span will show the matching translation-->

Now if you set key.expr = undefined, previously the old translated content was not removed. Now an empty string will shown instead.

Scenario#2: Fallback for null, or undefined key works differently.

Consider the following example.

  <span t="keyExpr">${value}</span>

Previously if the keyExpr is evaluated to null, or undefined, the evaluated value of value worked as fallback. With the new release, this fallback technique won't work. A similar fallback can be achieved by using the defaultValue parameter though.

  <span t="keyExpr" t-params.bind="{defaultValue: value}"></span>

aurelia-dialog 2.0.0

See previous pre-releases for changes from version 1.x.

Bug Fixes

  • Fix dialog mouse event bug

aurelia-pal-nodejs 2.0.0

Bug Fixes

  • platform: type mismatch ( c823413 )


Minor Releases

Minor updates include new features, updates to bugs, and performance improvements.

aurelia-ux 0.18.0

Thanks to our new core team member Ben Girardet , we've recently shipped a set of major improvements to Aurelia UX focused on theming and consistency across components.


New properties available in :

  • surfaceBackground: set main surface background, especially for cards
  • surfaceForeground: set main surface foreground, especially for cards
  • controlLabelColor: set the default label color for all controls
  • disabledBackground: set the default background for all disabled states
  • disabledForeground: set the default foreground for all disabled states
  • error: set here the default error color
  • onError: available for when you need to write text on top of a surface using the error color. It is currently not used in Aurelia UX components

Input Controls

Components that act as an input control are now more consistent and can be themed like Material Design components. Here's what's available:

Themable properties (same for all input-like components)

  • foreground
  • foregroundLabel
  • background
  • backgroundHover
  • activeColor
  • fontSize
  • letterSpacing
  • labelFontSize
  • labelLetterSpacing
  • lineHeight
  • labelLineHeight
  • borderColor
  • borderRadius
  • borderWidth
  • borderActiveWidth
  • disabledForeground
  • disabledBackground
  • error

Filled, Outline, Dense

  • change the style of the input with filled or outline variants
    • example: <ux-input variant="outline"></ux-input>
  • Reduce the visual impact of the input with dense
    • example: <ux-input dense></ux-input>

Floating Labels or Placeholder

  • Floating labels are the default way, but you can choose from below.
  • Use the label bindable for floating labels
  • Use the placeholder bindable for labels that disappear when field has a value
  • Use the <ux-field><label>...</label><ux-input>...</ux-input></ux-field> markup for labels that stay on top of the field all the time

Leading and Trailing Icons

  • All input controls host leading and trailing icons slots. The trailing icon is deactivated for ux-select and ux-datepicker due to the arrow and calendar icons present in the control by default
  • Example: <ux-input><ux-icon icon="person" slot="leading-icon"></ux-input>

Affected components:

  • ux-input
  • ux-textarea
  • ux-select
  • ux-datepicker
  • ux-chip-input


  • Removed some theme properties: flatBackground, flatForeground, textBackground, textForeground, outlineBackground and outlineBorder. Each of these colors is now derived from background and foreground or accentBackground and accentForeground.
  • Renamed backgroundDisabled and foregroundDisabled in disabledBackground and disabledForeground .


New ux-card-separator component.

  • This component makes it easy to add separator in cards (see Material Design guidelines).
  • By default it adds a vertical margin (up and down) of the separator. You can disable this margin with no-margin attribute.
  • You can include the separator between card parts (header and content for example) or inside the content. It will adjust its width accordingly.

Defaults to surface colors

  • Cards default color properties are now defaulted with the new surfaceBackground and surfaceForeground design properties.

New .ux-card__thumnail class.

Checkbox and Radio

  • Removed disableBorder theme property.
  • Replaces checkedBackground and checkmarkColor by activeColor.
  • Add the indeterminate state.


  • New ux-chip-list component.
  • ux-chip-input theme supports now all the new control theme properties.
  • ux-chip now has a selected state (bindable).
  • ux-chip also supports variants such as filled or outline.
  • ux-chip now has a thumbnail slot for icon or avatar purposes.


  • Add new trackHeight theme property.
  • Mobile-friendly: now works with touch gestures.

New Custom Attributes

The new ux-choice-container and ux-choice-item can be used to make any markup act as a selector component. It works particularly well with ux-list or ux-chip-list but you can use them anywhere. Here are two examples:

  <!-- bind a property to the ux-choice-container attribute to get the value of the choice -->
  <!-- bind a property to the ux-choice attribute to give it its choice value -->
  <ux-chip-list ux-choice-container.bind="labelPosition">
    <ux-chip variant="outline" ux-choice="floating">Floating</ux-chip>
    <ux-chip variant="outline" ux-choice="placeholder">Placeholder</ux-chip>
    <ux-chip variant="outline" ux-choice="top">On Top</ux-chip>
  <!-- If the bound property in ux-choice-container is an array, then the selector will allow multiple choices -->
  <ux-chip-list type="inline" ux-choice-container.bind="region">
    <ux-chip variant.bind="variant" ux-choice="basel">Basel</ux-chip>
    <ux-chip variant.bind="variant" ux-choice="bern">Bern</ux-chip>
    <ux-chip variant.bind="variant" ux-choice="geneva">Geneva</ux-chip>
    <ux-chip variant.bind="variant" ux-choice="lausanne">Lausanne</ux-chip>
    <ux-chip variant.bind="variant" ux-choice="zurich">Zürich</ux-chip>


This version does not automatically import any icons by default. From now on, you must decide on a per-project basis what icon sets you want to use.

Here are a few examples of how you can prepare your icon sets:

1. Import full set when configuring the plugin

As a quick start, you can import the same icon sets that were previously shipped with the package by configuring the plugin as such in your main.ts

  // main.ts
  /* Add this line to import the full set into an `icons` variable */
  import icons from '@aurelia-ux/icons/sets/full-array.min.json';
  /* When you initialize the plugin, you can pass on this `icons` variable */
  aurelia.use.plugin(PLATFORM.moduleName('@aurelia-ux/icons'), { icons });

2. Lazy loading later

  // app.ts
  import { inject } from 'aurelia-framework';
  import { UxIconMap } from '@aurelia-ux/icons';
  // here we import the full set from @aurelia-ux/icon but you can define any
  // icon set in the proper format (see below)
  import icons from '@aurelia-ux/icons/sets/full-array.min.json';
  export class App {
    constructor(private iconMap: UxIconMap) {

3. Import Font Awesome Icons

If you want to use Font Awesome icons, you can use them inside the <ux-icon> component. First you need to install the icons like:

  npm install @fortawesome/fontawesome-free

Then you can import them like so:

  // app.ts
  import { inject } from 'aurelia-framework';
  import { UxIconMap, UxIconRegArray } from '@aurelia-ux/icons';
  // You can import any font awesome set like so.
  // They will all become available in the ux-icon component
  import '@fortawesome/fontawesome-free/js/brands';
  import '@fortawesome/fontawesome-free/js/regular';
  const w = (window as any);
  export class App {
    constructor(private uxIconMap: UxIconMap) {
      if (w.___FONT_AWESOME___ && w.___FONT_AWESOME___.styles) {
        type FabIcon = [number, number, Array<any>, string, string];
        for (let fKey in (window as any).___FONT_AWESOME___.styles) {
          let fIcons: {[key: string]: FabIcon} = (window as any).___FONT_AWESOME___.styles[fKey];
          let fSet: Array<UxIconRegArray> = [];
          for (let iconKey in fIcons) {
            const icon = fIcons[iconKey];
            fSet.push([iconKey, `<path d="${icon[4]}"/></svg>`, icon[0], icon[1]]);

Registered icon list

You can get the list of all registered icons by calling iconMap.getAllKeys() which will return an Array<string> with all icon names. Knowing this, you could add the following code to your template to have a preview of all your registered icons with their names:

    <ux-card sm="2" repeat.for="name of uxIconMap.getAllKeys()">
      <ux-icon icon="${name}"></ux-icon>
      <br >${name}

Icon Set Format

You can register icons in an object or array form. The array form is slightly lighter.

  // array form
      "person", // icon name
      "<path d=\"M12 ...\"></path>", // svg path (without the svg tag)
      24, // optional (viewport width, default to 24)
      24 // optional (viewport height, default to 24)
  // object form
      "name": "person", // icon name
      "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M12 ...\"></path></svg>" // svg path (with the svg tag)

Importing JSON

Note for TypeScript users: Make sure that your tsconfig.json is set to allow importing JSON files. This can be achieved by setting "resolveJsonModule": true in the compilerOptions section.

aurelia-store 1.6.0


  • devtools: basic dispatcher support ( ca97e85 )

aurelia-store 1.5.0


  • devtools: implement redux devtools button handling ( #104 ) ( 86b7eda )

aurelia-templating-resources 1.13.0

Bug Fixes

  • all: change package.json module from es2015 back to native-modules ( 6a8f0c8 )
  • repeat: use utility fns for ie11 compat ( a59a2de )

aurelia-cli 1.3.0

Bug Fixes

  • missing semicolon in ts skeleton ( 5661b23 )
  • cli-bundler: avoid writing out webpack env json files ( 5893a67 )
  • docker: only copy config folder for webpack projs ( d560a4d )
  • protractor: fix chrome-driver issue on visible chrome too ( f45a7a9 )
  • tasks: update-all-dependencies should mutate original file, not dist file ( ec3a743 )
  • webpack: clean-webpack-plugin changed export ( 273a1f4 )


  • webpack: show aurelia-dialog patch for IE11 issue ( ff13245 )

Patch Releases

Patch updates include only fixes to bugs and performance improvements.

aurelia-templating 1.10.3

Bug Fixes

  • all: change es2015 back to native-modules ( ea50719 )
  • ElementEvents: ElementEvents.defaultListenerOptions allows to set default options when subscribing to events ( f7e8e32 ), closes #657
  • shadow-dom: prevent slot leak ( #678 ) ( 9241dca )