Ember.js Octane vs Classic Cheat Sheet

In classic Ember, ember generate component created three files: the template, a JavaScript file, and a test. In Octane, ember generate component skips creating the JavaScript file. If you want the backing JavaScript class as well, include the -gc option.

ember generate component my-component

# -gc stands for glimmer component
ember generate component my-component -gc

# -cc stands for classic component
ember generate component my-component -cc

# See the full set of options with this:
ember generate component --help

The location of component templates has changed in Octane. This is known as "template co-location."

app/
  components/
    my-component.js
  templates/
    components/
      my-component.hbs

app/
  components/
    my-component.hbs
    my-component.js

Angle brackets are a way to invoke components in a template file. There's no change in behavior. Learn more about features and using codemods to update your existing components.

{{my-component}}

<MyComponent />

Angle brackets components can be used as either inline or block components. There's no change in behavior. {{yield}} looks and works the same. Learn more about features and using codemods to update your existing components.

{{!-- inline --}}
{{my-component}}

{{!-- block --}}
{{#my-component as |text|}}
  some markup or {{text}}
{{/my-component}}

{{!-- inline --}}
<MyComponent />

{{!-- block --}}
<MyComponent as |text|>
  some markup or {{text}}
</MyComponent>

You can nest components in your file structure, and use them in a template with angle brackets invocation. There's no change in behavior.

{{ui-files/my-component}}

<UiFiles::MyComponent />

If a property was received from a parent component, refer to it with an @. There's no change in behavior. (Visit the Ember Guides to learn more.)

{{answer}} is the answer.

{{@answer}} is the answer.

If a property is defined in the JavaScript file for this component's template, use this when you refer to it. There's no change in behavior. Learn more about features and using codemods to update your existing components.

{{answer}} is the answer.

{{this.answer}} is the answer.

When you pass an argument to a component, use an @ symbol on the left hand side. There's no change in behavior. Learn more about features and using codemods to update your existing components.

{{my-component answer=answer}}

<MyComponent @answer={{@answer}} />

If a property is coming from a template's own JavaScript file, remember to put a this before it and wrap it in curly braces. Learn more about features and using codemods to update your existing components.

{{my-component answer=answer}}

<MyComponent @answer={{this.answer}} />

In Octane, components don't have a default wrapper anymore, so you don't need tagName! Just put the tag right in the template.

{{!-- parent-component.hbs --}}
{{child-component tagName="ul"}}

{{!-- child-component.hbs --}}
<li>item</li>
<li>item</li>

<!-- rendered output -->
<ul id="ember209" class="ember-view">
  <li>item</li>
  <li>item</li>
</ul>

{{!-- parent-component.hbs --}}
<ul>
  <ChildComponent />
</ul>

{{!-- child-component.hbs --}}
<li>item</li>
<li>item</li>

<!-- rendered output -->
<ul>
  <li>item</li>
  <li>item</li>
</ul>

Since components are tagless, there's no elementId, but you can generate your own. This is especially helpful for creating accessible forms.

import Component from '@ember/component';

export default Component.extend({
  didInsertElement() {
    console.log(this.elementId);
  }
});

<div class="form-group">
  <label for="textInput-{{elementId}}">{{inputLabelText}}</label>
  <input 
    id="textInput-{{elementId}}"
    name={{inputName}} 
    type="text" 
  />
</div>

import Component from '@glimmer/component';
import { guidFor } from '@ember/object/internals';

export default class InputTextComponent extends Component {
  inputId = 'textInput-' + guidFor(this); 
}

<div class="form-group">
  <label for={{this.inputId}}>{{@inputLabelText}}</label>
  <input 
    id={{this.inputId}} 
    name={{@inputName}} 
    type="text" 
  />
</div>

An Octane component imports from the @glimmer package namespace. It also uses native class syntax. Glimmer components have different API methods than classic components. If you aren't familiar with native classes, first check out the documentation on MDN. Then, learn more about Glimmer components from the Ember.js Guides and the API Reference.

import Component from '@ember/component';

export default Component.extend({
  init() {
    this._super(...arguments);
  }
});

import Component from '@glimmer/component';

export default class MyComponent extends Component {
  constructor() {
    super(...arguments);
  }
}

Properties follow native JavaScript class syntax. No commas!

import Component from '@ember/component';

export default Component.extend({
  min: 0,
  max: 100
});

import Component from '@glimmer/component';

export default class MyComponent extends Component {
  min = 0;
  max = 100;
}

Octane components enforce "Data Down, Actions Up." When data is passed down to a component, the only way to change that data is to call an action that was passed in too. In another words, there is no two-way binding for component arguments.

// parent-component.js
import Component from '@ember/component';

export default Component.extend({
  count: 0
});

{{!-- parent-component.hbs --}}
{{child-component count=count}}
Count: {{this.count}}

// child-component.js
import Component from '@ember/component';

export default Component.extend({
  actions: {
    plusOne() {
      this.set('count', this.get('count') + 1);
    }
  }
});

{{!-- child-component.hbs --}}
<button type="button" {{action "plusOne"}}>
  Click Me
</button>

// parent-component.js
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class ParentComponent extends Component {
  @tracked count = 0;

  @action plusOne() {
    this.count++;
  }
}

{{!-- parent-component.hbs --}}
<ChildComponent @plusOne={{this.plusOne}} />
Count: {{this.count}}

{{!-- child-component.hbs --}}
<button type="button" {{on "click" @plusOne}}>
  Click Me
</button>

In Octane, arguments are set on the args property, this.args. They are not set on the class instance, this. As a result, you can distinguish internal class values from external arguments. (Visit the Ember Guides to learn more about arguments.)

import Component from '@ember/component';
import { computed } from '@ember/object';

export default Component.extend({
  prefix: 'ISO',

  displayName: computed('prefix,isoStandardNumber', function() {
    /*
      There are two issues with this code:

      1. `prefix` may or may not be overriden from outside
      2. We can't tell if `isoStandardNumber` is a property or an argument
    */
    return `${this.prefix} ${this.isoStandardNumber}`;
  }),

  /* Rest of the code omitted */
});

import Component from '@glimmer/component';

export default class MyComponent extends Component {
  prefix = 'ISO';

  get displayName() {
    return `${this.prefix} ${this.args.isoStandardNumber}`;
  }

  /* Rest of the code omitted */
}

Octane components do not use this.get or this.set. Access and modify properties directly, the same as you would in a regular JavaScript class.

import Component from '@ember/component';

export default Component.extend({
  count: 0,

  actions: {
    minusOne() {
      this.set('count', this.get('count') - 1);
    }
  }
});

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';

export default class MyComponent extends Component {
  @tracked count = 0;

  @action minusOne() {
    this.count = this.count - 1;
  }
}

Label the properties that should be tracked. Getters will be updated automatically.

import Component from '@ember/component';
import { computed } from '@ember/object';

export default Component.extend({
  index: 0,

  nextIndex: computed('index', function() {
    return this.index + 1;
  })
});

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

export default class MyComponent extends Component {
  @tracked index = 0;

  get nextIndex() {
    return this.index + 1;
  }
}

In Octane, it is recommended to rewrite a computed property as tracked property. In case that isn't possible (maybe you need caching), the @computed decorator is available.

import Component from '@ember/component';
import { computed } from '@ember/object';

export default Component.extend({
  index: 0,

  nextIndex: computed('index', function() {
    return this.index + 1;
  })
});

import Component from '@glimmer/component';
import { computed } from '@ember/object';

export default class MyComponent extends Component {
  index = 0;

  @computed('index')
  get nextIndex() {
    return this.index + 1;
  }
}

In the JavaScript class, use the @action decorator to mark the function that you want to call from the template. In the template, use the {{on}} modifier to decide when to call the function. If you need to pass an argument to the function, use {{fn}} helper too. (Visit the Ember Guides to learn more.)

import Component from '@ember/component';

export default Component.extend({
  actions: {
    sayHello() {
      console.log('Hello, world!');
    },

    saySomethingElse(message) {
      console.log(message)
    }
  }
});

<button
  type="button"
  onclick={{action "sayHello"}}
>
  Say hello!
</button>

<button
  type="button"
  onclick={{action "saySomethingElse" "Cheese!"}}
>
  Say cheese!
</button>

import Component from '@glimmer/component';
import { action } from '@ember/object';

export default class MyComponent extends Component {
  @action sayHello() {
    console.log('Hello, world!');
  }

  @action saySomethingElse(message) {
    console.log(message);
  }
}

<button
  type="button"
  {{on "click" this.sayHello}}
>
  Say hello!
</button>

<button
  type="button"
  {{on "click" (fn this.saySomethingElse "Cheese!")}}
>
  Say cheese!
</button>

Because an argument is read-only, you cannot set its default value in the consuming class. Instead, you can create a getter to wrap the argument and provide the default value.

{{!-- parent-component.hbs --}}
{{child-component answer=answer}}

// child-component.js
import Component from '@ember/component';

export default Component.extend({
  answer: 42
});

{{!-- parent-component.hbs --}}
<ChildComponent @answer={{this.answer}} />

// child-component.js
import Component from '@glimmer/component';

export default class ChildComponent extends Component {
  get answer() {
    return this.args.answer ?? 42;
  }
}

You cannot use mixins on anything that uses native class syntax (e.g. components that import from @glimmer/component). The migration strategy depends on your use case. If your app depends on an addon that uses mixins, it may be best to continue using classic components until the addon is Octane-ready.

import Component from '@ember/component';
import SomeMixin from 'some-addon';

export default Component.extend(SomeMixin, {
  // ...
});

constructor comes from native JavaScript class. You can use this hook to set up the component class, similarly to what you might have done in init. (Visit the Ember Guides to learn more about constructor and super.)

import Component from '@ember/component';

export default Component.extend({
  init() {
    this._super(...arguments);
    this.set('answer', 42);
  }
});

import Component from '@glimmer/component';

export default class MyComponent extends Component {
  constructor(owner, args) {
    super(owner, args);
    this.answer = 42;
  }
}

willDestroy is the only other lifecycle hook (besides constructor) that Glimmer components have. You can use this hook to tear down the component class, similarly to what you might have done in willDestroyElement. (Visit the Ember Guides to learn more about lifecycle of Glimmer components.)

import Component from '@ember/component';

export default Component.extend({
  willDestroyElement() {
    // Remove event listener
  }
});

import Component from '@glimmer/component';

export default class MyComponent extends Component {
  willDestroy() {
    // Remove event listener
  }
}

If you install @ember/render-modifiers, you get {{did-insert}} and {{did-update}} modifiers. You may use them to replace a classic component's lifecycle hooks didInsertElement, didRender, and didUpdate.

ember install @ember/render-modifiers

If you used the didInsertElement hook, consider making an action. You can call the action with the {{did-insert}} modifier. Use the @action decorator to bind the correct context (this). (Visit the Ember Guides to learn more about lifecycle of Glimmer components.)

<canvas id="my-canvas"></canvas>

import Component from '@ember/component';

export default Component.extend({
  didInsertElement() {
    // Find the canvas element by id. Then, create a graph.
  }
});

<canvas {{did-insert this.createGraph}}></canvas>

import Component from '@glimmer/component';
import { action } from '@ember/object';

export default class MyComponent extends Component {
  @action createGraph(element) {
    // You have the canvas element. Now make the graph!
  }
}

In a route template, the model comes from an outside context. Use @model to access the result from the route's model hook.

First name: {{model.firstName}}

First name: {{@model.firstName}}