Template Tag Format

When you use the .gjs (or .gts) file extension, you're adding one extra syntax feature to JavaScript (or TypeScript): the <template> tag.

<template> can be used in two different positions: as expressions and inside class bodies.

When you use a <template> tag as an expression, you're defining a template-only component:

const Greeting = <template>Hello World</template>

And if you put a <template> tag expression by itself in module scope:

<template>Hello World</template>

That is shorthand for also saying export default:

export default <template>Hello World</template>

A <template> tag can also be embedded inside a class body:

import Component from '@glimmer/component';

export default class Avatar extends Component {
  get titleWithDefault() {
    return this.args.title ?? 'No avatar title provided';
  }

  <template>
    <aside>
      <div class="avatar" title={{this.titleWithDefault}}>{{@initial}}</div>
    </aside>
  </template>
}

This associates the template with the class. When the resulting Avatar component is invoked, it's the <template> that will be rendered, with this bound to an instance of the Avatar class.

<template> tags have access to the surrounding JavaScript scope. For example:

const value = 2;

function square(number) {
  return number * number;
}

<template>
  The square of {{value}} equals {{square value}}
</template>

This will render to The square of 2 equals 4.

Because we have <template> tag expressions and access to local scope, you can define multiple components in a single JavaScript module and let them call each other:

const Option = <template>
  <option selected={{@selected}} value={{@value}}>
    {{@value}}
  </option>
</template>;

const CustomSelect = <template>
  <select>
    {{#each @options as |opt|}}
      <Option
        @value={{opt.value}}
        @selected={{eq opt @selectedOption}}
      />
    {{/each}}
  </select>
</template>;

export default CustomSelect;

This can be a powerful refactoring technique to break up large components into smaller ones. (where it makes sense!)

In Ember templates, “invokables” are things you can invoke in a template. These include components, helpers, and modifiers. In the template tag format, most invokables need to be in JavaScript scope. Therefore your module must either define them or import them.

A small number of commonly-used invokables are always available, without needing to import them. This includes on for event handling, boolean logic helpers like and, comparisons like eq, and others. See the full list on the Ember Helpers API Docs.

Built-in invokables have lower precedence than your local JavaScript scope, so that future built-ins will never break your existing code.

All of template-tag format has an equivalent pure-JS representation.

The template-only-component case converts like this:

// ----- GJS Syntax ------------------------
import { pageTitle } from "ember-page-title";

const LandingPage = <template>
  {{pageTitle "Welcome"}}
  <h1>Welcome</h1>
</template>;

// ------ Equivalent JS Syntax -------------
import { pageTitle } from "ember-page-title";
import { template } from '@ember/template-compiler';

const LandingPage = template(`{{pageTitle "Welcome"}}
<h1>Welcome</h1>`, {
  scope: () => ({ pageTitle })
})

And the class-based-component case converts likes this:

// ------ GJS Syntax ---------------
import { pageTitle } from "ember-page-title";

class LandingPage extends Component {
  <template>
    {{pageTitle "Welcome"}}
    <h1>Welcome</h1>
  </template>
}

// ------ Equivalent JS Syntax -------------
import { pageTitle } from "ember-page-title";
import { template } from '@ember/template-compiler';

class LandingPage extends Component {
  static {
    template(`{{pageTitle "Welcome"}}
<h1>Welcome</h1>`, {
      component: this,
      scope: () => ({ pageTitle })
    });
  }
}

Just like the <template></template> syntax, template() from @ember/template-compiler can be build-time optimized, so you're not allowed to use any syntax other than string literals for the first argument. For example:

import { template } from '@ember/template-compiler';

// This is OK because the first argument to template() is a string literal:
const LandingPage = template(`{{pageTitle "Welcome"}}
<h1>Welcome</h1>`, {
  scope: () => ({ pageTitle })
})

// This is a build error because the first argument is not a string literal:
const LandingPage = template(buildTemplate(), {
  scope: () => ({ pageTitle })
})

function buildTemplate() {
  return `{{pageTitle "Welcome"}}
<h1>Welcome</h1>`;
}

If you want to relax this restriction, you can opt-in to runtime template compilation instead. This is more expensive at runtime and pulls additional template-compilation code into your app. But it's appropriate for dynamic environments like interactive development tools:

// Notice the different import path here:
import { template } from '@ember/template-compiler/runtime';

// This is now OK because no static build-time analysis will 
// be performed, and you can use arbitrary code to produce a 
// string value at runtime.
const LandingPage = template(buildTemplate(), {
  scope: () => ({ pageTitle })
})

function buildTemplate() {
  return `{{pageTitle "Welcome"}}
<h1>Welcome</h1>`;
}

The <template> syntax in GJS is able to "see" outer JavaScript scope (like the value of pageTitle in the examples above). When we convert the template to a JavaScript string, that's no longer possible, so we need to add either the scope or eval arguments. The examples above use scope, which is best when you know precisely which values from JavaScript scope are needed inside the template. For more dynamic situations, you can alternatively pass eval:

import { template } from '@ember/template-compiler/runtime';

template(someArbitraryTemplateString(), {
  eval() {
    return eval(arguments[0]);
  }
})

The above example is the only way you should implement the eval callback. It uses arguments instead of an explicitly-named function parameter because otherwise that parameter could shadow the value that the template compiler is trying to retrieve from an outer scope.

<template> tag expressions make it easy to write component tests. See Testing Components for details.

  test('renders name argument', async function (assert) {
    const initial = 'Zoey';
    await render(
      <template>
        <Avatar @title="Picture of Zoey" @initial={{initial}} />
      </template>
    );
    assert.dom().hasText(initial);
  });
});

These tools have minimum versions to support Template Tag:

• ember-template-lint: Versions 5.8.0 and up.
• eslint-plugin-ember: Versions 11.6.0 and up.
• Prettier: Versions 3.1.0 and up. This requires installing the prettier-plugin-ember-template-tag.
• Glint: Requires installing the environment-ember-template-imports plugin.

You may need to configure your editor to get syntax highlighting inside embedded templates and support for the .gjs and .gts file extension.

The Ember.js extension pack bundles everything you need to get started. More specifically, the vscode-glimmer-syntax extension will add support for glimmer-js and glimmer-ts languages and provide syntax highlighting. The ember-language-server extension provides automatic import completions and other useful features.

Here's an example Neovim Config with support for good highlighting of embedded templates in JS and TS, using:

• nvim-treesitter
• tree-sitter-glimmer

For other editors, you may be able to get support using one of these other syntax definitions:

• TextMate
• TreeSitter