Using aurelia-ux v0.6

aurelia-ux is the pre-release UI component kit for aurelia. It has been developed throughout 2017 including a significant re-organization between v0.3 and v0.4. Due to this reorganization and its pre-release status, there is limited information out there on how to use it, with the best example at present being aurelia-store-todo. There is an indication that documentation is on the way and hopefully as part of that the team’s app-ux-showcase will be updated past v0.3. In the meantime I decided to dig into the source a bit and build a little something to share here.

Setup

This setup assumes you have aurelia-cli running, so that you can go to a command line and type au new to create the project. Open the project folder and add the following dependencies to the package.json then run npm install (or the yarn equivalent) to get the aurelia-ux packages into your node_modules folder:

  "@aurelia-ux/components": "^0.6.0",
  "@aurelia-ux/core": "^0.6.0",

aurelia-store-todo uses WebPack as the bundler, however I will be sticking to the aurelia-cli. This means editing the aurelia.json to include the dependencies. The first dependency is @aurelia-ux/core which contains the core capabilities. Then each component needs to be added individually. There is also an @aurelia-ux/components which may be intended to include all components, but including this causes build errors as the require exports for all the referenced components are not able to be resolved. The additions to the vendor-bundle dependencies in aurelia.json look something like this:

{
  "name": "@aurelia-ux/core",
  "path": "../node_modules/@aurelia-ux/core/dist/amd",
  "main": "index",
  "resources": ["**/*.{css,html}"]
},
{
  "name": "@aurelia-ux/input",
  "path": "../node_modules/@aurelia-ux/input/dist/amd",
  "main": "index",
  "resources": ["**/*.{css,html}"]
},
{
  "name": "@aurelia-ux/button",
  "path": "../node_modules/@aurelia-ux/button/dist/amd",
  "main": "index",
  "resources": ["**/*.{css,html}"]
},
{
  "name": "@aurelia-ux/form",
  "path": "../node_modules/@aurelia-ux/form/dist/amd",
  "main": "index",
  "resources": ["**/*.{css,html}"]
}

Using Components

The components are added as plugins to main.ts, like so:

aurelia.use
    .plugin(PLATFORM.moduleName('@aurelia-ux/core'))
    .plugin(PLATFORM.moduleName('@aurelia-ux/input'))
    .plugin(PLATFORM.moduleName('@aurelia-ux/button'))
    .plugin(PLATFORM.moduleName('@aurelia-ux/form'));

This makes them available everywhere, without needing further require tags.

Each component has a tag and properties which can be used in a template file. For instance the button is <ux-button> and can be bound to a view model variable using value.bind e.g. <ux-input value.bind="rows"></ux-input>. The elements appear unmodified in the output HTML and can be styled using CSS. Here is an example of using three components in a view model.
app.html:

<template>
  <require from="./app.css"></require>
  <ux-form>
    Rows:<ux-input value.bind="rows"></ux-input>
    Columns: <ux-input value.bind="cols"></ux-input>
    <ux-button type="raised" click.trigger="generate()">Generate</ux-button>
  </ux-form>
</template>

app.ts:

export class App {
    protected rows: number = 5; // arbitrary default
    protected cols: number = 5; // arbitrary default
    protected generate() { ... }
}

app.css (you may need to create this):

ux-form {
    padding: 2px;
    max-width: 300px;
    border: 1px solid transparent;
    border-color: var(--ux-design--primary-light)
}

CSS Variables

You may have noticed in the CSS above the use of a variable: var(--ux-design--primary-light). This is a mechanism for globally styling aurelia-ux, and is setup in the app constructor as follows:

import { autoinject } from 'aurelia-framework';
import { AureliaUX } from '@aurelia-ux/core';

@autoinject
export class App {
    protected rows: number = 5; // arbitrary default
    protected cols: number = 5; // arbitrary default

    // ux.design members: 
    //     appBackground, appForeground, controlBackground, controlForeground, 
    //     primary, primaryForeground, primaryLight, primaryLightForeground, primaryDark, primaryDarkForeground, 
    //     accent, accentForeground, accentLight, accentLightForeground, accentDark, accentDarkForeground
    constructor(private ux: AureliaUX) {
        ux.design.primary = '#DD0088';
        ux.design.accent = '#CC88FF';
        // unfortunately we don't seem to be able to change the tints by just setting the base color, so set them as well
        ux.design.primaryLight = '#DB9BBF';
        ux.design.accentLight = '#E7C9FF';
    }

    protected generate() { ... }
}

The name of the CSS variable is --ux-design--<property-name> where the property name is one of the ux.design members above. You can see them all in your browser’s CSS viewer:
CSS Design Variables
It is worth noting that CSS variables do not work in IE11 so if you expect to support that browser then aurelia-ux may not be suitable for you.

More

This is as far as I’ve gone with aurelia-ux so far, but there’s certainly more out there.

There are 11 components as it stands: button; checkbox; chip-input (a tag list); datepicker; form; input; input-info; list; radio; textarea; and switch. To find out what properties they expose download and run app-ux-showcase, or open your node_modules/@aurelia-ux/<name>/dist/amd/ux-<name>.d.ts and look at the public properties and methods.

There is also a themeing system which enables you to define your own component themes by extending implementations of the UxTheme class. Any properties in those classes can be used as CSS variables. To fully grasp this at present I’d suggest downloading the aurelia-ux source.