Tracked Properties

It's not uncommon to use POJOs in Ember code for storing state, representing some models, etc. This works because get and set can be used for any path, on any object, whether or not its an EmberObject, and whether or not the property was declared in advance. This is part of what lead to the "implicit" property problem - you set any property you wanted on an existing object and it would work.

With tracked properties this is not possible, since each property must be instrumented ahead of time, and decorators can only be applied in classes. In general, the recommendation here is to convert usages of POJOs to native classes wherever possible:

// Before
import EmberObject, { computed } from '@ember/object';

const Person = EmberObject.extend({
  init() {
    this.address = {};
  },

  fullAddress: computed('address.{street,city,region,country}', function() {
    let { street, city, region, country } = this.address;

    return `${street}, ${city}, ${state}, ${country}`;
  }),
});

// After
import { tracked } from '@glimmer/tracking';

class Address {
  @tracked street;
  @tracked city;
  @tracked region;
  @tracked country;
}

class Person {
  address = new Address();

  get fullAddress() {
    let { street, city, region, country } = this.address;

    return `${street}, ${city}, ${state}, ${country}`;
  }
}

In some cases, if your usage of properties on POJOs is too dynamic, you may not be able to enumerate every single property that could be tracked. There could be a prohibitive number of possible properties, or there could be no way to know them in advance. In this case, it's recommended that you reset the value wherever it is updated:

class SimpleCache {
  @tracked _cache = {};

  set(key, value) {
    this._cache[key] = value;

    // trigger an update
    this._cache = this._cache;
  }

  get(key) {
    return this._cache[key];
  }
}

Triggering an update like this will cause any getters that used the _cache to recalculate. Note that we can use the get method to access the cache, and it will still push the _cache tracked property.

Arrays are another example of a type of object where you can't enumerate every possible value - after all, there are an infinite number of integers (though you may run out of bits in your computer at some point!). Instead, you can continue to use EmberArray, which will continue to work with tracking and will cause any dependencies that use it to invalidate correctly.

import { A } from '@ember/array';

class ShoppingList {
  items = A([]);

  addItem(item) {
    this.items.pushObject(item);
  }
}

Tracked properties are fully backwards compatible with computed properties and get/set. Computed properties can depend on tracked properties like any other dependency:

import { tracked } from '@glimmer/tracking';
import { computed } from '@ember/object';

class Image {
  @tracked width;

  @computed('width', 'height')
  get aspectRatio() {
    return this.width / this.height;
  }
}

let profilePhoto = new Image();

// This will correctly invalidate `aspectRatio`
profilePhoto.width = 200;

Note, however, that if you want to use a getter as a dependent key, you will need to use the dependentKeyCompat decorator. This allows you to refactor existing computed properties into getters without breaking existing code that observes them.

Vice-versa, computed properties used in native getters will autotrack and cause the getter to update correctly:

class Image {
  @computed('width', 'height')
  get aspectRatio() {
    return this.width / this.height;
  }

  get helloMessage() {
    return `Image aspect ratio is: ${this.aspectRatio}!`;
  }
}

Likewise, properties that are not decorated with @tracked that you get using get will also autotrack, and update later on when you use set to update them:

class Image {
  get aspectRatio() {
    let width = get(this, 'width');
    let height = get(this, 'height');

    return width / height;
  }
}

let profilePhoto = new Image();
set(profilePhoto, 'width', 300);
set(profilePhoto, 'height', 300);

However, you must use get for these properties, since they are not tracked and there is no way to know in advance that they might be changed with set. For instance, this will not work:

class Image {
  get aspectRatio() {
    return this.width / this.height;
  }
}

let profilePhoto = new Image();
set(profilePhoto, 'width', 250);
set(profilePhoto, 'height', 250);

Additionally, certain Ember objects still require the use of get and set, such as ObjectProxy and ArrayProxy. These will continue to function with tracked, but you must use get and set. Likewise, KVO methods on Ember's Enumerable class, such as objectAt and pushObject, and the various implementations of it will generally continue to be tracked.

If you have implemented your own version of an Ember Enumerable, or the EmberArray mixin, in general, you will need to add an additional step to your implementation of objectAt in order for it to work with tracking:

objectAt() {
  get(this, '[]');

  // your implementation
}

This will push the tag for the [] property onto the autotrack stack, and that property is what is invalidated when the array is updated with KVO methods.

Ember's classic change tracking system used two methods to ensure that all data was accessed properly and updated correctly: get and set.

import { get, set } from '@ember/object';

let image = {};

set(image, 'width', 250);
set(image, 'height', 500);

get(image, 'width'); // 250
get(image, 'height'); // 500

In classic Ember, all property access had to go through these two methods. Over time, these rules have become less strict, and now they have been minimized to just a few cases. In general, in a modern Ember app, you shouldn't need to use them all that much. As long as you are marking your properties as @tracked, Ember should automatically figure out what needs to change, and when.

However, there still are two cases where you will need to use them:

• When accessing and updating plain properties on objects without decorators
• When using Ember's ObjectProxy class, or a class that implements the unknownProperty function (which allows objects to intercept get calls)

Additionally, you will have to continue using accessor functions for arrays if you want arrays to update as expected. These functions are covered in more detail in the Looping Through Lists guide.

Importantly, you do not have to use get or set when reading or updating computed properties, as was noted in the computed property section.

In general, if a value in your application could update, and that update should trigger rerenders, then you should mark that value as @tracked. This oftentimes may mean taking a POJO and turning it into a class, but this is usually better because it forces us to rationalize the object - think about what its API is, what values it has, what data it represents, and define that in a single place.

However, there are times when data is too dynamic. As noted below, proxies are often used for this type of data, but usually they're overkill. Most of the time, all we want is a POJO.

In those cases, you can still use get and set to read and update state from POJOs within your getters, and these will track automatically and trigger updates.

class Profile {
  photo = {
    width: 300,
    height: 300,
  };

  get photoAspectRatio() {
    return get(this.photo, 'width') / get(this.photo, 'height');
  }
}

let profile = new Profile();

// render the page...

set(profile.photo, 'width', 500); // triggers an update

This is also useful when working with older Ember code which has not yet been updated to tracked properties. If you're unsure, you can use get and set to be safe.

Ember has and continues to support an implementation of a Proxy, which is a type of object that can wrap around other objects and intercept all of your gets and sets to them. Native JavaScript proxies allow you to do this without any special methods or syntax, but unfortunately they are not available in IE11. Since many Ember users must still support IE11, Ember's ObjectProxy class allows us to accomplish something similar.

The use cases for proxies are generally cases where some data is very dynamic, and its not possible to know ahead of time how to create a class that is decorated. For instance, ember-m3 is an addon that allows Ember Data to work with dynamically generated models instead of models defined using @attr, @hasMany, and @belongsTo. This cuts back on code shipped to the browser, but it means that the models have to dynamically watch and update values. A proxy allows all accesses and updates to be intercepted, so m3 can do what it needs to do without predefined classes.

Most ObjectProxy classes have their own get and set method on them, like EmberObject classes. This means you can use them directly on the class instance:

proxy.get('width');
proxy.set('width', 100);

If you're unsure whether or not a given object will be a proxy or not, you can still use Ember's get and set functions:

get(maybeProxy, 'width');
set(maybeProxy, 'width', 100);