Ember.js Cheat Sheet Cheat Sheet

This guide is a cheat sheet for using Ember.js. The examples are for Ember 7.3 and use the <template> tag. It doesn't cover everything, but it should get you started! PRs welcome at the GitHub repository.

For in-depth information, see The Ember Guides.

Understanding Templates

Grammar

Ember's template grammar is an intentionally simple language so that the underlying GlimmerVM can be fast. It is built on Symbolic Expressions (S-Expressions) which is a tree-based structure for helping simplify syntax, building, and parsing templates.
If you're familiar with TypeScript, you could define the template grammar using this pseudo-code here, like so,

type Value = string | number | null | undefined | object | Value[];
type Helper = Function | EmberHelper | EmberModifier;
type NamedArgs = Key + '=' + SExpression
type SExpression =
  | Value
  | `(` + Helper + `)`
  | `(` + Helper + ...SExpression + `)`
  | `(` + Helper + ...SExpression + ...NamedArgs + `)`

type Moustache = `{{` + SExpression + `}}`

A plain function works as a helper. No addon and no wrapper are necessary, because Ember calls the function with the positional arguments. If there are named arguments, the function receives them in one object as its last parameter.

<div>
    {{a b c d=e}}
{{!-- │ │ │ │ └─── value / s-expression
      │ │ │ └─── named argument key
      │ │ └─── positional argument
      │ └─── positional argument
      └─── helper --}}
</div>

In this example, a can only be a helper. Each of b, c, and e cannot be anything other than plain values because functions cannot be invoked without surrounding parentheses.

Notation

Unlike JavaScript, Ember templates use Polish Notation or Prefix Notation which means that operators (or functions) precede their operands (arguments).

{{or argA (not argB)}}

{{functionA argA argB argC=(functionB argD)}}

which is the equivalent of this, in JavaScript

argA || !argB;

functionA(argA, argB, { argC: functionB(argD) });

In Ember 7.3, or, not, and the other logical and comparison helpers are part of Ember. In .hbs templates and in older versions of Ember, an addon such as ember-truth-helpers supplies them.

Syntax

Syntax plays an important role in the template, because based on the position of an expression in the template, you'll know exactly what type of thing it is: a modifier, a helper, or plain value

<div {{modifierName a b=(helperName c)}}>
  {{yield to="default"}}
</div>

It doesn't matter how the reference to a modifier or a helper is written, it is the syntax which determines what is expected.

<div {{this.modifierName a b=(this.helperName c)}}>
{{!--  │                 │ │  │               └─── positional argument
       │                 │ │  └─── helper
       │                 │ └─── named argument key
       │                 └─── positional argument
       └─── modifier --}}
  {{yield to="default"}}
{{!--  │  │   └─── value
       │  └─── named argument key
       └─── helper --}}
</div>

<div {{@modifierName a b=(@helperName c)}}>
{{!--  │             │ │  │           └─── positional argument
       │             │ │  └─── helper
       │             │ └─── named argument key
       │             └─── positional argument
       └─── modifier --}}
  {{yield to="default"}}
{{!--  │  │   └─── value
       │  └─── named argument key
       └─── helper --}}
</div>

Built-in Helpers and Modifiers

In Ember 7.3, these names work in every <template> tag without an import: and, array, element, eq, fn, gt, gte, hash, lt, lte, neq, not, on, and or. The same is true for the keywords of the template language, such as if, each, let, yield, and component.

<template>
  {{#if (and @isAdmin (not @isLocked))}}
    <button type="button" {{on "click" (fn @onDelete @user)}}>
      Delete
    </button>
  {{/if}}
</template>

Other helpers need an import in a .gjs or .gts file. In a .hbs template, Ember finds helpers by name. Of the names above, only array, fn, hash, and on are built in there. An addon must supply the others.

import { concat, get, uniqueId } from '@ember/helper';

<template>
  {{#let (uniqueId) as |id|}}
    <label for={{id}}>{{get @labels @field}}</label>
    <input id={{id}} class={{concat "field-" @field}} />
  {{/let}}
</template>

How To

Iteration

each renders its block one time for each item of an array or of another iterable. The second block parameter is the index. The else block renders when the list is empty.

{{#each this.anIterable as |item index|}}
  {{index}}: {{item}}
{{else}}
  The list is empty.
{{/each}}

By default, Ember identifies each item by its object identity. When the list gets new objects for the same items, give key the name of a property that has a unique value. Ember then keeps the DOM of each item.

{{#each this.anIterable key='uuid' as |item|}}
  {{item.name}}
{{/each}}

each-in renders its block one time for each key of an object.

{{#each-in this.anObject as |key value|}}
  {{key}}: {{value}}
{{/each-in}}

Invoking Functions

To call a function, write its name and then the arguments, as you do for a helper. The function can be an import, a local variable, an argument, or a property of this.

import Price from './price';

const formatPrice = (cents, currency = 'USD') => {
  const format = new Intl.NumberFormat('en-US', { style: 'currency', currency });

  return format.format(cents / 100);
};

<template>
  {{formatPrice @cents}}
  {{formatPrice @cents "EUR"}}

  <Price @label={{formatPrice @cents}} />
</template>

A function with arguments is always called. A function without arguments is called when its result goes directly into the page. Where the function is the value of an argument, add parentheses to call it. Without the parentheses, the argument receives the function itself, not its result.

{{(this.myFunction)}}

<Price @label={{(this.myFunction)}} />

Accessing Properties

Use a path with dots to read a property of an argument, of this, or of a block parameter. If a value in the path is missing, the result is undefined, and there is no error.

{{@argumentA}}
{{@user.address.city}}
{{this.property}}

Use the get helper when the property name is a value, or when it is not a valid identifier.

import { get } from '@ember/helper';

<template>
  {{get @argObject 'property-name'}}
  {{get @argObject @dynamicProperty}}
</template>

Accessing Array Indices

Use the get helper with the index. The index can be a literal or a value.

import { get } from '@ember/helper';

<template>
  {{get @someArray 0}}
  {{get @someArray @index}}
</template>

Conditions

if renders its block when the value is truthy. In templates, an empty array is falsy, which is different from JavaScript. unless is the opposite of if.

{{#if this.condition}}
  ...
{{else if this.otherCondition}}
  ...
{{else}}
  ...
{{/if}}
{{#unless this.condition}}
  ...
{{/unless}}

Inline, if returns its second argument when the condition is truthy. If not, it returns its third argument.

<div class={{if @isActive "active" "inactive"}}>
  {{if @name @name "No name"}}
</div>

Combine conditions with the comparison helpers and the logical helpers. In a <template> tag, they are part of Ember 7.3 and need no import.

{{#if (eq @a @b)}}
  ...
{{/if}}

{{#if (or (eq @a @b) (gt @c 0))}}
  ...
{{/if}}

{{if (and @a (not @b)) "is true" "is false"}}

Defining Variables

Using let is the only way to define variables inline in templates. Because let is a block-helper, it means that scope is consistent with other blocks in templates as well. This is different from languages like JavaScript, where defining a variable is accessible to the "current scope" -- with let, you create a new scope.

{{#let (array 1 2 3) as |list|}}
  {{#each list as |number|}}
    {{number}}
  {{/each}}
{{/let}}

In this example, an array is created and then available within the let block as list. It can be iterated over just as any array defined in JavaScript would be.

In a .gjs or .gts file, a JavaScript variable outside of the <template> is frequently simpler.

const list = [1, 2, 3];

<template>
  {{#each list as |number|}}
    {{number}}
  {{/each}}
</template>

Math

The comparison helpers gt, gte, lt, and lte are part of Ember 7.3. Ember has no helpers for arithmetic. Write a function, and call it in the template.

const add = (a, b) => a + b;

<template>
  {{add @count 1}}

  {{#if (gt @count 10)}}
    More than ten.
  {{else if (lte @count 0)}}
    None.
  {{/if}}
</template>