Ember-custom-elements NPM

Ember Custom Elements

The most flexible way to render parts of your Ember application using custom elements!

Demos

Tic Tac Toe game using Ember and React (based on the React.js tutorial)
Super Rentals w/ animated route transitions (combines custom elements for routes with Ionic Framework's animated nav)
Nifty Squares (demonstrates dynamic block content)

Compatibility

Ember.js v3.8 or above
Ember CLI v2.13 or above
Node.js v10 or above

This add-on won't work at all with versions of ember-source prior to 3.6.0. I will not be actively trying to support versions of Ember that are not recent LTS versions, but I'm open to any pull requests that improve backward compatibility.

Installation

ember install ember-custom-elements

If you are targeting older browsers, you may want to use a polyfill for custom elements. Other features of web components are also available as polyfills.

Usage

Components

All you have to do is use the customElement decorator in your component file:

import Component from '@glimmer/component';
import { customElement } from 'ember-custom-elements';

@customElement('my-component')
export default MyComponent extends Component {

}

Now you can use your component anywhere inside the window that your app was instantiated within by using your custom element:

<my-component></my-component>

In the case that you can't use TC39's proposed decorator syntax, you can call customElement as a function and pass the target class as the first argument:

export default customElement(MyComponent, 'my-component');

However, it's recommended that you upgrade to a recent version of ember-cli-babel so you can use decorator syntax out of the box, or manually install babel-plugin-proposal-decorators.

In newer versions of Ember, you will get a linting error if you have an empty backing class for your component. Since the @customElement decorator needs to be used in a JS file in order to implement a custom element for your component, you may have no choice but to have an empty backing class.

Thus, you may want to disable the ember/no-empty-glimmer-component-classes ESLint rule in your Ember project. In the future, we will explore ways to define custom elements for tagless components, but until then you either need a component class defined.

Attributes and Arguments

Attributes instances of your custom element are translated to arguments to your component:

<my-component some-message="hello world"></my-component>

To use the attribute in your component template, you would use it like any other argument:

{{!-- my-component.hbs --}}
{{@some-message}}

Changes to attributes are observed, and so argument values are updated automatically.

Block Content

Block content inside your custom element instances can be treated just like block content within a precompiled template. If your component contains a {{yield}} statement, that's where the block content will end up.

{{!-- my-component.hbs --}}
<span>foo {{yield}} baz</span>

<my-component>bar</my-component>

When the component is rendered, we get this:

<span>foo bar baz</span>

Block content can be dynamic. However, the consuming element needs to be able to handle its children being changed by other forces outside of it; if a child that's dynamic gets removed by the custom element itself, that can lead to the renderer getting confused and spitting out errors during runtime.

You can see dynamic block content can work in this demo.

Routes

The @customElement decorator can define a custom element that renders an active route, much like the {{outlet}} helper does. In fact, this is achieved by creating an outlet view that renders the main outlet for the route.

Just like with components, you can use it directly on your route class:

/* app/routes/posts.js */

import Route from '@ember/routing/route';
import { customElement } from 'ember-custom-elements';

@customElement('test-route')
export default class PostsRoute extends Route {
  model() {
    ...
  }
}

In this case, the <test-route> element will render your route when it has been entered in your application.

Named Outlets

If your route renders to named outlets, you can define custom elements for each outlet with the outletName option:

/* app/routes/posts.js */

import Route from '@ember/routing/route';
import { customElement } from 'ember-custom-elements';

@customElement('test-route')
@customElement('test-route-sidebar', { outletName: 'sidebar' })
export default class PostsRoute extends Route {
  model() {
    ...
  }

  renderTemplate() {
    this.render();
    this.render('posts/sidebar', {
      outlet: 'sidebar'
    });
  }
}

In this example, the <test-route-sidebar> element exhibits the same behavior as {{outlet "sidebar"}} would inside the parent route of the posts route. Notice that the outletName option reflects the name of the outlet specified in the call to the render() method.

Note that the use of renderTemplate is being deprecated in newer versions of Ember.

Outlet Element

This add-on comes with a primitive custom element called <ember-outlet> which can allow you to dynamically render outlets, but with a few differences from the {{outlet}} helper due to technical limitations from rendering outside of a route hierarchy.

Usage

The outlet element will not be defined by default. You must do this with the @customElement decorator function. Here is an example of an instance-initializer you can add to your application that will set up the outlet element:

// app/custom-elements.js

import { setOwner } from '@ember/application';
import { customElement, EmberOutletElement } from 'ember-custom-elements';

@customElement('ember-outlet')
export default class OutletElement extends EmberOutletElement {

}

This will allow you to render an outlet like this:

<ember-outlet></ember-outlet>

By default, the <ember-outlet> will render the main outlet for the application route. This can be useful for rendering an already initialized Ember app within other contexts.

To render another route, you must specify it using the route= attribute:

<ember-outlet route="posts.index"></ember-outlet>

If your route specifies named routes, you can also specify route names:

<ember-outlet route="posts.index" name="sidebar"></ember-outlet>
<ember-outlet route="posts.index" name="content"></ember-outlet>

Since an <ember-outlet> can be used outside of an Ember route, the route attribute is required except if you want to render the application route. You cannot just provide the name= attribute and expect it to work.

In the unusual circumstance where you would be loading two or more Ember apps that use the ember-outlet element on the same page, you can extend your own custom element off the ember-outlet in order to resolve the naming conflict between the two apps.

Applications

You can use the same @customElement decorator on your Ember application. This will allow an entire Ember app to be instantiated and rendered within a custom element as soon as that element is connected to a DOM.

Presumably, you will only want your Ember app to be instantiated by your custom element, so you should define autoboot = false; in when defining your app class, like so:

/* app/app.js */

import Application from '@ember/application';
import Resolver from 'ember-resolver';
import loadInitializers from 'ember-load-initializers';
import config from './config/environment';
import { customElement } from 'ember-custom-elements';

@customElement('ember-app')
export default class App extends Application {
  modulePrefix = config.modulePrefix;
  podModulePrefix = config.podModulePrefix;
  Resolver = Resolver;
  autoboot = false;
  // 👆 this part is important
}

loadInitializers(App, config.modulePrefix);

Once your app has been created, every creation of a custom element for it will only create new application instances, meaning that your instance-initializers will run again but your initializers won't perform again. Custom elements for your app are tied directly to your existing app.

Native Custom Elements

The customElement decorator can also be used on native custom elements (i.e. extensions of HTMLElement).

/* app/custom-elements/my-element.js */
import { customElement } from 'ember-custom-elements';

@customElement('my-element')
export default class MyElement extends HTMLElement {

}

There's a few minor things that this add-on does for you when it comes to using plain custom elements:

If you need to access the application from a descendent class of HTMLElement, you can use Ember.getOwner anywhere in your custom element code.
The connectedCallback will only be called after Glimmer has had a chance to render the block of content passed to your custom element. This has to happen because Glimmer inserts elements individually, so even though your custom element may have been connected to the DOM, its prospective children probably haven't been inserted yet.
Service injection is possible like with any other Ember class using the @inject decorator from @ember/service. (In pre-Octane Ember, you of course need a polyfill for ES decorators)

It's important that your custom elements are located in a folder named app/custom-elements so that they can be properly registered with your application. This add-on will NOT infer the tagName of the elements from their respective file names; you must always use the @customElement decorator.

Options

At present, there are a few options you can pass when creating custom elements:

extends: A string representing the name of a native element your custom element should extend from. This is the same thing as the extends option passed to window.customElements.define().
useShadowRoot: By default, application content rendered in your custom elements will be placed directly into the main DOM. If you set this option to true, a shadow root will be used.
observedAttributes: A whitelist of which element attributes to observe. This sets the native observedAttributes static property on custom elements. It's suggested that you only use this option if you know what you are doing, as once the observedAttributes are set on a defined custom element, it cannot be changed after the fact(remember that custom elements can be only defined once). The most common reason to define observedAttributes would be for performance reasons, as making calls to JavaScript every time any attribute changes is more expensive than if only some attribute changes should call JavaScript. All that said, you probably don't need this, as ember-custom-elements observes all attribute changes by default. Does nothing for custom elements that instantiate Ember apps.
customElementClass: In the extreme edge case that you need to redefine the behavior of the custom element class itself, you can import { EmberCustomElement } from 'ember-custom-elements';, extend it into a subclass, and pass that subclass to the customElementClass option. This is definitely an expert tool and, even if you think you need this, you probably don't need it. This is made available only for the desperate. The EmberCustomElement class should be considered a private entity.
camelizeArgs: Element attributes must be kabob-case, but if camelizeArgs is set to true, these attributes will be exposed to your components in camelCase.
outletName: (routes only) The name of an outlet you wish to render for a route. Defaults to 'main'. The section on named outlets goes into further detail.
preserveOutletContent: (routes only) When set to true, this prevents the DOM content inside the element from being cleared when transition away from the route is performed. This is false by default, but you may want to set this to true in the case where you need to keep the DOM content around for animation purposes.

Options Example

@customElement('my-component', { extends: 'p', useShadowRoot: true })
export default MyComponent extends Component {

}

Global Default Options

In the case where you want to apply an option to all uses of the customElement decorator, you can set the option as a global default in the config/environment.js of your Ember project.

For example, if you want preserveOutletContent to be applied to all route elements, you can add this option to ENV.emberCustomElements.defaultOptions:

module.exports = function(environment) {
  ...
  emberCustomElements: {
    defaultOptions: {
      preserveOutletContent: true
    }
  },
  ...
}

Accessing a Custom Element

The custom element node that's invoking a component can be accessed using the getCustomElement function.

Simply pass the context of a component; if the component was invoked with a custom element, the node will be returned:

import Component from '@glimmer/component';
import { customElement, getCustomElement } from 'ember-custom-elements';

@customElement('foo-bar')
export default class FooBar extends Component {
  constructor() {
    super(...arguments);
    const element = getCustomElement(this);
    // Do something with your element
    this.foo = element.getAttribute('foo');
  }
}

Forwarding Component Properties

HTML attributes can only be strings which, while they work well enough for many purposes, can be limiting.

If you need to share state between your component and the outside world, you can create an interface to your custom element using the forwarded decorator. Properties and methods upon which the decorator is used will become accessible on the custom element node. If an outside force sets one of these properties on a custom element, the value will be set on the component. Likewise, a forwarded method that's called on a custom element will be called with the context of the component.

import Component from '@glimmer/component';
import { customElement, forwarded } from 'ember-custom-elements';

@customElement('foo-bar')
export default class FooBar extends Component {
  @forwarded
  bar = 'foobar';

  @forwarded
  fooBar() {
    return this.bar.toUpperCase();
  }
}

When rendered, you can do this:

const element = document.querySelector('foo-bar');
element.bar; // 'foobar'
element.fooBar(); // 'FOOBAR"

If you are using tracked from @glimmer/tracking, you can use it in tandem with the forwarded decorator on properties.

Notes

Elements

Once a custom element is defined using window.customElements.define, it cannot be redefined.

This add-on works around that issue by reusing the same custom element class and changing the configuration associated with it. It's necessary in order for application and integration tests to work without encountering errors. This behavior will only be applied to custom elements defined using this add-on. If you try to define an application component on a custom element defined outside of this add-on, an error will be thrown.

Runloop

Because element attributes must be observed, the argument updates to your components occur asynchronously. Thus, if you are changing your custom element attributes dynamically, your tests will need to use await settled().