Aurelia provides a multitude of different wants to observe properties in your components and call a callback function when they change.

The following sections in the observation documentation will help you decide which observation strategy is appropriate for your applications, from the most commonly used to more advanced observation strategies.

The @observable approach

The easiest way to watch for changes to specific view model properties is using the @observable decorator which provides an easy way to watch for changes to properties and react accordingly.

Effect observation approach

While still using the @observable API, the effect observation approach has more boilerplate and is convenient for instances where you want to observe one or more effects. Examples include when the user moves their mouse or other changes you might want to watch, independent of the component lifecycle.

HTML observation approach

Unlike other forms of observation, HTML observation is when you want to watch for changes to specific properties on elements, especially for web component properties.

The observer locator approach

The observer locator API allows you to observe properties for changes manually. In many instances, you will want to use @observer or @watch however, the observer locator can be useful in situations where you want to watch the properties of objects.

The Observer Locator API allows you to watch properties in your components for changes without the need for using the @observable decorator. In most cases, manual observation will not be required using this API, but it is there if you want it.

Basic observer interface

By default, an observer locator is used to create observers and subscribe to them for change notification.

A basic observer has the following interface:

interface IObserver {
  subscribe(subscriber)
  unsubscribe(subscriber)
}

The subscribe method of an observer can be used to subscribe to the changes that it observes. This method takes a subscriber as its argument.

A basic subscriber has the following interface:

interface ISubscriber {
  handleChange(newValue, oldValue)
}

Getting an observer of a property

An observer of an object property can be retrieved using an observer locator.

An example of this is:

// getting the observer for property 'value'
const observer = observerLocator.getObserver(obj, 'value')

And to subscribe to changes emitted by this observer:

const subscriber = {
  handleChange(newValue) {
    console.log('new value of object is:', newValue)
  }
}

observer.subscribe(subscriber)

// and to stop subscribing
observer.unsubscribe(subscriber)

Getting an observer of an expression

It's not always sufficient to observe a single property on an object, and it's sometimes more desirable to return a computed value from the source so that subscribers of an observer don't have to perform any logic dealing with the updated values. An example of this is the follow observation of firstName and lastName to notify full name:

const obj = { firstName: '', lastName: '' }
function notifyFullnameChanged() {
  console.alert(`${obj.firstName} ${obj.lastName}`);
}
const observer1 = observerLocator.getObserver(obj, 'firstName').subscribe({ handleChange: notifyFullnameChanged })
const observer2 = observerLocator.getObserver(obj, 'lastName').subscribe({ handleChange: notifyFullnameChanged })

Doing it the way above is cumber some as we need to setup 2 observers and 2 subscribers, also there's a typo risk. We can also use a getter to express a computed value, and then observe that getter to avoid having to do heavy setup work:

const obj = { firstName: '', lastName: '', get fullName() { return `${this.firstName} ${this.lastName}` } }
const observer = observerLocator.getObserver(obj, 'fullName').subscribe({ handleChange: fullname => alert(fullname) });

This is not always feasible since the obj could be from a 3rd party library, or some json data from server, and the risk of having a typo fullName is still there.

Aurelia provides another API of creating observer to deal with this scenario, where it's more desirable to use a function/lambda expression to express the dependencies and computed value to notify the subscriber. To use this API, replace the 2nd parameter of getObserver with a getter function to express the value:

const obj = { firstName: '', lastName: '' }
const observer = observerLocator.getObserver(obj, obj => `${obj.firstName} ${obj.lastName}`).subscribe({
  handleChange: fullname => alert(fullname)
});

Quick introduction

HTML elements are special objects that often require different observation strategies, and most of the time, listening to some specific event is the preferred way. For this reason, Aurelia encourages using events to observe HTML elements.

As an example, the value property of an <input /> element should be observed by listening to the <input /> change events such as input or change on the element. Another example is the value property of a <select /> element should be observed by listening to the change event on it.

By default, the observation of HTML elements is done using a default node observer locator implementation. This default locator has a basic set of APIs that allows users to teach Aurelia how to observe HTML element observation effectively.

The following is the trimmed interface of the node observer locator, highlighting its capability to learn how to observe HTML elements:

export class NodeObserverLocator {
  allowDirtyCheck: boolean;
  handles(obj, key, requestor): boolean;

  useConfig(config): void;
  useConfig(nodeName, key, eventsConfig): void;

  useConfigGlobal(config): void;
  useConfigGlobal(key, eventsConfig): void;
}

useConfig and useConfigGlobal are two methods that can be used to teach the default node observer locator what events can be used to observe a property of a specific element or any element.

Node observer examples

Using the nodeObserverLocator API, we can tell Aurelia how to observe properties of HTML elements for changes. Under the hood, Aurelia already observes properties like values on form inputs, but it is good to understand how this functionality works, especially for custom elements and web components.

How to teach Aurelia to observe the value property of a <textarea /> element:

nodeObserverLocator.useConfig('textarea', 'value', { events: ['input', 'change'] });

In this example, the eventsConfig argument has the value { events: ['input', 'change']}.

How to teach Aurelia to observe property length of an <input /> element:

nodeObserverLocator.useConfig('input', 'length', { events: ['input'] });

In this example, eventsConfig argument has the value { events: ['input']}.

How to teach Aurelia observe property scrollTop of all elements:

nodeObserverLocator.useConfigGlobal('scrollTop', { events: ['scroll'] });

In this example, eventsConfig argument has the value { events: ['scroll']}.

Observing custom elements in Web Components

It should be the same as observing custom (HTML) elements and normal HTML elements. It is common for Web Components to have well-defined events associated with their custom properties, so observing them often means adding a few configuration lines.

An example of how to teach Aurelia to observe the value property of a <my-input /> element, and <my-input /> dispatches valueChanged event when its value has been changed:

nodeObserverLocator.useConfig('my-input', 'value', { events: ['valueChanged'] });

Unlike the @watch decorator, the @observable decorator allows you to decorate properties in a component and optionally call a change callback when the value changes. It works quite similarly to the @bindable property.

By convention, the change handler is a method whose name is composed of the property_name and the literal value 'Changed'. For example, if you decorate the property color with @observable, you have to define a method named colorChanged() to be the change handler.

This is what a basic observable would look like using conventions:

import { observable } from 'aurelia';

export class Car {
  @observable color = 'blue';

  colorChanged(newValue, oldValue) {
    // this will fire whenever the 'color' property changes
  }
}

When the color value is changed, the colorChanged callback will be fired. The new changed value will be the first argument, and the existing one will be the second one.

If you prefer, you can also put the @observable decorator on classes:

import { observable } from 'aurelia';

@observable('color')
@observable({ name: 'speed', callback: 'speedCallback' })
export class Car {
  color = 'blue';
  speed = 300;

  colorChanged(newValue, oldValue) {
    // this will fire whenever the 'color' property changes
  }

  speedCallback(newValue, oldValue) {
    // this will fire whenever the 'speed' property changes
  }
}

Specifying a different change callback

If you do not want to use the convention, you can define the callback name for the change handler by setting the callback property of the @observable decorator:

import { observable } from 'aurelia';

export class Car {
  @observable({ callback: 'myCallback' }) color = 'blue';

  myCallback(newValue, oldValue) {
    // this will fire whenever the 'color' property changes
  }
}

Aurelia provides a higher-level API for simplifying some common tasks to handle a common reactivity intent in any application: run a function again when any of its dependencies have been changed.

This function is called an effect, and the dependencies are typically tracked when they are accessed (read) inside this effect function. The builtin @observable decorator from Aurelia enables this track-on-read capability by default.

Aurelia provides a few ways to declare a dependency for an effect function. The most common one is the track "on read" of a reactive property.

In the following example:

class MouseTracker {
  @observable
  coord = [0, 0];
}

The property coord of a MouseTracker instance will be turned into a reactive property and is also aware of effect function dependency tracking.

The effect APIs are provided via the default implementation of the interface IObservation, which can be retrieved like one of the following examples:

• Getting from a container directly:

import { IObservation } from 'aurelia';

...
const observation = someContainer.get(IObservation);

• Getting through injection:

import { inject, IObservation } from 'aurelia';

@inject(IObservation)
class MyElement {
  constructor(observation) {
    // ...
  }
}

Or

class MyElement {
  constructor(@IObservation readonly observation) {
    // ...
  }
}

After getting the observation object, there are two APIs that can be used to created effects as described in the following sections:

Watch effect

Watch effect is a way to describe a getter based observation of an object. An example to create watch effect is per the following:

import { inject, IObservation } from 'aurelia';

@inject(IObservation)
class PersonalInfo {
  constructor(observation) {
    const effect = observation.watch(this.primaryInfo, (primaryInfo) => primaryInfo.name, function nameChanged(newName, oldName) {
      // do something with name
    });

    // effect.stop() later when necessary
  }
}

Note that the effect function will be run immediately. If you do not want to run the callback immediately, pass an option immediate: false as the 4th parameter:

observation.watch(obj, getter, callback, { immediate: false });

By default, a watch effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation instance has stopped. To stop/destroy an effect, call the method stop() on the effect object.

Run effect

Run effects describe a function to be called repeatedly whenever any dependency tracked inside it changes.

Creating an Effect

After getting an IObservation instance, a run effect can be created via the method run of it:

const effect = observation.run(() => {
  // code here
});

Note that the effect function will be run immediately.

By default, a effect is independent of any application lifecycle, which means it does not stop when the application that owns the observation instance has stopped. To stop/destroy an effect, call the method stop() on the effect object:

const effect = IObservation.run(() => {
  // code here
});

// stop the effect like this
effect.stop();

Effect examples

The following section gives some examples of what it looks like when combining @observable and run effect.

Creating a run effect that logs the user mouse movement on the document

import { inject, IObservation, observable } from 'aurelia'

class MouseTracker {
  @observable coord = [0, 0]; // x: 0, y: 0 is the default value
}

// Inside an application:
@inject(IObservation)
class App {
  constructor(observation) {
    const mouseTracker = new MouseTracker();

    document.addEventListener('mousemove', (e) => {
      mouseTracker.coord = [e.pageX, e.pageY]
    });

    observation.run(() => {
      console.log(mouseTracker.coord)
    });
  }
}

Now whenever the user moves the mouse around, a log will be added to the console with the coordinate of the mouse.

Creating a run effect that sends a request whenever user focus/unfocus the browser tab

import { inject, IObservation, observable } from 'aurelia'

class PageActivity {
  @observable active = false
}

// Inside an application:
@inject(IObservation)
class App {
  constructor(observation) {
    const pageActivity = new PageActivity();

    document.addEventListener(visibilityChange, (e) => {
      pageActivity.active = !document.hidden;
    });

    observation.run(() => {
      fetch('my-game/user-activity', { body: JSON.stringify({ active: pageActivity.active }) })
    });
  }
}