NOTE: Sustain is currently only available for Ember <= 2.9. Glimmer 2 support will be added eventually.

Use the sustain helper to explicitly declare component instances that can be recycled. This lets Ember recycle a component instance and it's associated DOM across layout and route boundaries.

{{sustain 'foo-component'}}

A sustain is essentially a "marker" for where a particular component instance should be inserted.

Since the component a sustain specifies is moved from marker to marker, only one marker instance for a given component name can be used at a time, unless a unique label is provided.

This produces a significant performance advantage by allowing you to seamlessly restructure your app's DOM when shifting from one layout or route to another without needing to teardown and rebuild DOM.

Providing a model for your component

{{sustain 'foo-component' model}}

Complex Models

Use the hash helper to handle more complex model situations.

{{sustain 'foo-component' (hash emails=model.emails foo=(action 'foo') bar=bar)}}

Dealing with animation and other scenarios in which two instances exist at once.

Only one instance of the sustainable is alive and rendered at a time, but if you are animating from one location to another you can choose to leave behind a copy.

{{sustain 'foo-component' copy=true)}}

Configuring the component's cache expire time.

By default, a sustain is destroyed when it has gone unused for 15 seconds. You can alter this expiration. A value of 0 or -1 will cause the sustain to live forever.

{{sustain 'foo-component' expires=0}}

Multiple Instances / Labeling a sustain

If you need more than one instance of a component to be recyclable, you may provide a unique label for the sustain. The instance will only be reused in locations where that label appears in conjunction with the same Component Name.

{{sustain 'foo-component' model label="foo-1"}}
{{sustain 'foo-component' model label="foo-2"}}

Lifecycle Hooks

The component being sustained has access to two new hooks: willMove and didMove. For both, a method by that name on your component will trigger before the event fires.

  • willMove: fires before a component instance leaves a location
  • didMove: fires when a component instance has entered a location

On the initial render and insertion of a sustained component, only didMove triggers.