This addon provides an API for authoring element modifiers in Ember. It mirrors Ember's helper API, with variations for writing both simple function-based modifiers and more complicated class-based modifiers.
NOTE: this is the README for the v4 release. For the v3 README, see here.
- Ember.js v3.24 or above
- Embroider or ember-auto-import v2.0.0 or above (this is v2 addon)
This project follows the current draft of the Semantic Versioning for TypeScript Types proposal.
- Currently supported TypeScript versions: v5.0 - v5.5
- Compiler support policy: simple majors
- Public API: all published types not in a
-private
module are public
ember install ember-modifier
Modifiers are a basic primitive for interacting with the DOM in Ember. For
example, Ember ships with a built-in modifier, {{on}}
:
All modifiers get applied to elements directly this way (if you see a similar value that isn't in an element, it is probably a helper instead), and they are passed the element when applying their effects.
Conceptually, modifiers take tracked, derived state, and turn it into some sort of side effect related in some way to the DOM element they are applied to.
A "side effect" is something that happens in programming all the time. Here's an example of one in an Ember component that attempts to make a button like in the first example, but without modifiers:
// 🛑 DO NOT COPY THIS 🛑
import Component from '@glimmer/component';
export default class MyButton extends Component {
get setupEventHandler() {
document.querySelector('#my-button').addEventListener(this.args.onClick);
return undefined;
}
}
We can see by looking at the setupEventListener
getter that it isn't actually
returning a value. Instead, it always returns undefined
. However, it also adds
the @onClick
argument as an event listener to the button in the template
when the getter is run, as the template is rendering, which is a side effect
- it is an effect of running the code that doesn't have anything to do with the "main" purpose of that code, in this case to return a dynamically computed value. In fact, this code doesn't compute a value at all, so this component is misusing the getter in order to run its side effect whenever it is rendered in the template.
Unmanaged side effects can make code very difficult to reason about, since any function could be updating a value elsewhere. In fact, the code above is very buggy:
- If the
@onClick
argument ever changes, it won't remove the old event listener, it'll just keep adding new ones. - It won't remove the old event listener when the component is removed.
- It uses a document element selector that may not be unique, and it has no guarantee that the element will exist when it runs.
- It will run in Fastboot/Server Side Rendering, where no DOM exists at all, and it'll throw errors because of this.
However, there are lots of times where its difficult to write code that doesn't have side effects. Sometimes it would mean having to rewrite a large portion of an application. Sometimes, like in the case of modifying DOM, there isn't a clear way to do it at all with just getters and components.
This is where modifiers come in. Modifiers exist as a way to bridge the gap between derived state and side effects in way that is contained and consistent, so that users of a modifier don't have to think about them.
Let's look again at our original example:
We can see pretty clearly from this template that Ember will:
- Create a
<button>
element - Append the contents of the
@text
argument to that button - Add a click event handler to the button that runs the
@onClick
argument
If @text
or @onClick
ever change, Ember will keep everything in sync for us.
We don't ever have to manually set element.textContent
or update anything
ourselves. In this way, we can say the template is declarative - it tells
Ember what we want the output to be, and Ember handles all of the bookkeeping
itself.
Here's how we could implement the {{on}}
modifier so that it always keeps
things in sync correctly:
import { modifier } from 'ember-modifier';
export default modifier((element, [eventName, handler]) => {
element.addEventListener(eventName, handler);
return () => {
element.removeEventListener(eventName, handler);
}
});
Here, we setup the event listener using the positional parameters passed to the
modifier. Then, we return a destructor - a function that undoes our setup,
and is effectively the opposite side effect. This way, if the @onClick
handler ever changes, we first teardown the first event listener we added -
leaving the element in its original state before the modifier ever ran - and
then setup the new handler.
This is what allows us to treat the {{on}}
modifier as if it were just like
the {{@text}}
value we put in the template. While it is side effecting, it
knows how to setup and teardown that side effect and manage its state. The side
effect is contained - it doesn't escape into the rest of our application, it
doesn't cause other unrelated changes, and we can think about it as another
piece of declarative, derived state. Just another part of the template!
In general, when writing modifiers, especially general purpose/reusable modifiers, they should be designed with this in mind. Which specific effects are they trying to accomplish, how to manage them effectively, and how to do it in a way that is transparent to the user of the modifier.
This addon does not provide any modifiers out of the box. Instead, this library allows you to write your own. There are two ways to write modifiers:
- Function-based modifiers
- Class-based modifiers
These are analogous to Ember's Helper APIs, helper
and Helper
.
modifier
is an API for writing simple modifiers. For instance, you could
implement Ember's built-in {{on}}
modifier like so with modifier
:
// /app/modifiers/on.js
import { modifier } from 'ember-modifier';
export default modifier((element, [eventName, handler]) => {
element.addEventListener(eventName, handler);
return () => {
element.removeEventListener(eventName, handler);
}
});
Function-based modifiers consist of a function that receives:
- The
element
- An array of positional arguments
- An object of named arguments
modifier((element, positional, named) => { /* */ });
This function runs the first time when the element the modifier was applied to is inserted into the DOM, and it autotracks while running. Any tracked values that it accesses will be tracked, including the arguments it receives, and if any of them changes, the function will run again.1
The modifier can also optionally return a destructor. The destructor function will be run just before the next update, and when the element is being removed entirely. It should generally clean up the changes that the modifier made in the first place.
To create a modifier (and a corresponding integration test), run:
ember g modifier scroll-top
For example, if you wanted to implement your own scrollTop
modifier (similar
to this), you may do something like this:
// app/modifiers/scroll-top.js
import { modifier } from 'ember-modifier';
export default modifier((element, [scrollPosition]) => {
element.scrollTop = scrollPosition;
})
If the functionality you add in the modifier needs to be torn down when the element is removed, you can return a function for the teardown method.
For example, if you wanted to have your elements dance randomly on the page
using setInterval
, but you wanted to make sure that was canceled when the
element was removed, you could do:
// app/modifiers/move-randomly.js
import { modifier } from 'ember-modifier';
const { random, round } = Math;
export default modifier(element => {
const id = setInterval(() => {
const top = round(random() * 500);
const left = round(random() * 500);
element.style.transform = `translate(${left}px, ${top}px)`;
}, 1000);
return () => clearInterval(id);
});
Ember Inspector supports showing modifiers. For Function-Based Modifiers it shows the function name as modifier name. By default arrow functions or unamed functions will be shown as <unknown>. To have a name shown in the inspector use a named function or pass an extra option.
export default modifier(element => {
...
}, { name: 'my-fn-modifier' });
Sometimes you may need to do something more complicated than what can be handled by function-based modifiers. For instance:
- You may need to inject services and access them
- You may need fine-grained control of updates, either for performance or convenience reasons, and don't want to teardown the state of your modifier every time only to set it up again.
- You may need to store some local state within your modifier.
In these cases, you can use a class-based modifier instead. Here's how you
would implement the {{on}}
modifier with a class:
import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable';
function cleanup(instance: OnModifier) {
let { element, event, handler } = instance;
if (element && event && handler) {
element.removeEventListener(event, handler);
instance.element = null;
instance.event = null;
instance.handler = null;
}
}
export default class OnModifier extends Modifier {
element = null;
event = null;
handler = null;
modify(element, [event, handler]) {
this.addEventListener(element, event, handler);
registerDestructor(this, cleanup)
}
// methods for reuse
addEventListener = (element, event, handler) => {
// Store the current element, event, and handler for when we need to remove
// them during cleanup.
this.element = element;
this.event = event;
this.handler = handler;
element.addEventListener(event, handler);
};
}
While this is slightly more complicated than the function-based version, but that complexity comes along with much more control.
As with function-based modifiers, the lifecycle hooks of class modifiers are tracked. When they run, then any values they access will be added to the modifier, and the modifier will update if any of those values change.
To create a modifier (and a corresponding integration test), run:
ember g modifier scroll-top --class
For example, let's say you want to implement your own {{scroll-position}}
modifier (similar to this).
This modifier can be attached to any element and accepts a single positional
argument. When the element is inserted, and whenever the argument is updated, it
will set the element's scrollTop
property to the value of its argument.
(Note that this example does not require the use of a class, and could be implemented equally well with a function-based modifier!)
// app/modifiers/scroll-position.js
import Modifier from 'ember-modifier';
export default class ScrollPositionModifier extends Modifier {
modify(element, [scrollPosition], { relative }) {
if(relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
Usage:
// app/components/scroll-container.js
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
import { action } from '@ember/object';
export default class ScrollContainerComponent extends Component {
@tracked scrollPosition = 0;
@action scrollToTop() {
this.scrollPosition = 0;
}
}
If the functionality you add in the modifier needs to be torn down when the
modifier is removed, you can use registerDestructor
from @ember/destroyable
.
For example, if you want to have your elements dance randomly on the page using
setInterval
, but you wanted to make sure that was canceled when the modifier
was removed, you could do this:
// app/modifiers/move-randomly.js
import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable'
const { random, round } = Math;
const DEFAULT_DELAY = 1000;
function cleanup(instance) {
if (instance.setIntervalId !== null) {
clearInterval(instance.setIntervalId);
instance.setIntervalId = null;
}
}
export default class MoveRandomlyModifier extends Modifier {
element = null;
setIntervalId = null;
constructor(owner, args) {
super(owner, args);
registerDestructor(this, cleanup);
}
modify(element, _, { delay }) {
// Save off the element the first time for convenience with #moveElement
if (!this.element) {
this.element = element;
}
// Reset from any previous state.
cleanup(this);
this.setIntervalId = setInterval(this.#moveElement, delay ?? DEFAULT_DELAY);
}
#moveElement = (element) => {
let top = round(random() * 500);
let left = round(random() * 500);
this.element.style.transform = `translate(${left}px, ${top}px)`;
};
}
Usage:
You can also use services into your modifier, just like any other class in Ember.
For example, suppose you wanted to track click events with ember-metrics
:
// app/modifiers/track-click.js
import { inject as service } from '@ember/service';
import Modifier from 'ember-modifier';
import { registerDestructor } from '@ember/destroyable';
function cleanup(instance) {
instance.element?.removeEventListener('click', instance.onClick, true);
}
export default class TrackClick extends Modifier {
@service metrics;
constructor(owner, args) {
super(owner, args);
registerDestructor(this, this.cleanup);
}
modify(element, [eventName], options) {
this.element = element;
this.eventName = eventName;
this.options = options;
this.cleanup();
element.addEventListener('click', this.onClick, true);
}
onClick = () => {
this.metrics.trackEvent(this.eventName, this.options);
};
}
Usage:
constructor(owner, args)
- Constructor for the modifier. You must call
super(...arguments)
before performing other initialization. modify(element, positionalArgs, namedArgs)
- The primary hook for running a modifier. It gets called when the modifier is installed on the element, and any time any tracked state it uses changes. That tracked state can be from its arguments, which are auto-tracked, or from any other kind of tracked state, including but not limited to state on injected services.
Both the function- and class-based APIs can be used with TypeScript!
Before checking out the Examples with Typescript below, there is an important caveat you should understand about type safety!
There are, today, two basic approaches you can take to dealing with your modifier's arguments and element in a type safe way:
- You can use a type definition which specifies those for the outside world, relying on tooling like Glint to check that the invocation is correct, and treat input as safe accordingly.
- You can provide the minimal public interface which all modifiers conform to, and do runtime type checking with
assert
calls to make your internal implementation safe.
If you have a code base which is strictly typed from end to end, including with template type checking via Glint, then (1) is a great choice. If you have a mixed code base, or are publishing an addon for others to use, then it's usually best to do both (1) and (2)!
To handle runtime checking, for non-type-checked templates (including projects not yet using Glint or supporting external callers), you should act as though the arguments passed to your modifier can be anything. They’re typed as unknown
by default, which means by default TypeScript will require you to work out the type passed to you at runtime. For example, with the ScrollPositionModifier
shown above, you can combine TypeScript’s type narrowing with the default types for the class to provide runtime errors if the caller passes the wrong types, while providing safety throughout the rest of the body of the modifier. Here, modify
would be guaranteed to have the correct types for scrollPosition
and relative
:
import Modifier from 'ember-modifier';
import { assert } from '@ember/debug';
export class ScrollPositionModifier extends Modifier {
modify(element, [scrollPosition], { relative }) {
assert(,
`first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition}`,
typeof scrollPosition === "number"
);
assert(
`'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative}`,
typeof relative === "boolean"
);
if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
If you were writing for a fully-typed context, you can define your Modifier
with a Signature
interface, similar to the way you would define your signature for a Glimmer Component:
// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';
interface ScrollPositionModifierSignature {
Args: {
Positional: [number];
Named: {
relative: boolean;
};
};
}
export default class ScrollPositionModifier
extends Modifier<ScrollPositionModifierSignature> {
modify(element, [scrollPosition], { relative }) {
if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
Besides supporting integration with Glint, this also provides nice hooks for documentation tooling. Note, however, that it can result in much worse feedback in tests or at runtime if someone passes the wrong kind of arguments to your modifier and you haven't included assertions: users who pass the wrong thing will just have the modifier fail. For example, if you fail to pass the positional argument, scrollPosition
would simply be undefined
, and then element.scrollTop
could end up being set to NaN
. Whoops! For that reason, if your modifier will be used by non-TypeScript consumers, you should both publish the types for it and add dev-time assertions:
// app/modifiers/scroll-position.ts
import Modifier from 'ember-modifier';
interface ScrollPositionModifierSignature {
Args: {
Positional: [scrollPosition: number];
Named: {
relative: boolean;
};
};
Element: Element; // not required: it'll be set by default
}
export default class ScrollPositionModifier
extends Modifier<ScrollPositionModifierSignature> {
modify(element, [scrollPosition], { relative }) {
assert(,
`first argument to 'scroll-position' must be a number, but ${scrollPosition} was ${typeof scrollPosition}`,
typeof scrollPosition === "number"
);
assert(
`'relative' argument to 'scroll-position' must be a boolean, but ${relative} was ${typeof relative}`,
typeof relative === "boolean"
);
if (relative) {
element.scrollTop += scrollPosition;
} else {
element.scrollTop = scrollPosition;
}
}
}
The Signature
for a modifier is the combination of the positional and named arguments it receives and the element to which it may be applied.
interface Signature {
Args: {
Named: {
[argName: string]: unknown;
};
Positional: unknown[];
};
Element: Element;
}
When writing a signature yourself, all of those are optional: the types for modifiers will fall back to the correct defaults of Element
, an object for named arguments, and an array for positional arguments. You can apply a signature when defining either a function-based or a class-based modifier.
In a function-based modifier, the callback arguments will be inferred from the signature, so you do not need to specify the types twice:
interface MySignature {
Element: HTMLMediaElement;
Args: {
Named: {
when: boolean;
};
Positional: [];
};
}
const play = modifier<MySignature>((el, _, { when: shouldPlay }) => {
if (shouldPlay) {
el.play();
} else {
el.pause();
}
})
You never need to specify a signature in this way for a function-based modifier: you can simply write the types inline instead:
const play = modifier(
(el: HTMLMediaElement, _: [], { when: shouldPlay }: { when: boolean}) => {
if (shouldPlay) {
el.play();
} else {
el.pause();
}
}
);
However, the explicit modifier<Signature>(...)
form is tested to keep working, since it can be useful for documentation!
The same basic approach works with a class-based modifier:
interface MySignature {
// ...
}
export default class MyModifier extends Modifier<MySignature> {
// ...
}
In that case, the element
and args
will always have the right types throughout the body. Since the type of args
in the constructor are derived from the signature, you can use the ArgsFor
type helper to avoid having to write the type out separately:
import Modifier, { ArgsFor } from 'ember-modifier';
interface MySignature {
// ...
}
export default class MyModifier extends Modifier<MySignature> {
constructor(owner: unknown, args: ArgsFor<MySignature>) {
// ...
}
}
ArgsFor
isn't magic: it just takes the Args
from the Signature
you provide and turns it into the right shape for the constructor: the Named
type ends up as the named
field and the Positional
type ends up as the type for args.positional
, so you could write it out yourself if you preferred:
import Modifier from 'ember-modifier';
interface MySignature {
// ...
}
export default class MyModifier extends Modifier<MySignature> {
constructor(
owner: unknown,
args: {
named: MySignature['Args']['Named'];
positional: MySignature['Args']['Positional'];
}
) {
// ...
}
}
Let’s look at a variant of the move-randomly
example from above, implemented in TypeScript, and now requiring a named argument, the maximum offset. Using the recommended combination of types and runtime type-checking, it would look like this:
// app/modifiers/move-randomly.js
import { modifier } from 'ember-modifier';
import { assert } from '@ember/debug';
const { random, round } = Math;
export default modifier(
(element: HTMLElement, _: [], named: { maxOffset: number }
) => {
assert(
'move-randomly can only be installed on HTML elements!',
element instanceof HTMLElement
);
const { maxOffset } = named;
assert(
`The 'max-offset' argument to 'move-randomly' must be a number, but was ${typeof maxOffset}`,
typeof maxOffset === "number"
);
const id = setInterval(() => {
const top = round(random() * maxOffset);
const left = round(random() * maxOffset);
element.style.transform = `translate(${left}px, ${top}px)`;
}, 1000);
return () => clearInterval(id);
});
A few things to notice here:
-
TypeScript correctly infers the base types of the arguments for the function passed to the modifier; you don't need to specify what
element
orpositional
ornamed
are unless you are doing like we are in this example and providing a usefully more-specific type to callers. -
If we returned a teardown function which had the wrong type signature, that would also be an error.
If we return a value instead of a function, for example:
export default modifier((element, _, named) => { // ... return id; });
TypeScript will report:
Type 'Timeout' is not assignable to type 'void | Teardown'.
Likewise, if we return a function with the wrong signature, we will see the same kinds of errors. If we expected to receive an argument in the teardown callback, like this:
export default modifier((element, _, named) => { // return (interval: number) => clearTimeout(interval); });
TypeScript will report:
Type '(interval: number) => void' is not assignable to type 'void | Teardown'.
To support correctly typing args
in the constructor
for the case where you do runtime type checking, we supply an ArgsFor
type utility. (This is useful because the Signature
type, matching Glimmer Component and other "invokable" items in Ember/Glimmer, has capital letters for the names of the types, while args.named
and args.positional
are lower-case.) Here’s how that would look with a fully typed modifier that alerts "This is a typesafe modifier!" an amount of time after receiving arguments that depends on the length of the first argument and an optional multiplier (a nonsensical thing to do, but one that illustrates a fully type-safe class-based modifier):
import Modifier, { ArgsFor, PositionalArgs, NamedArgs } from 'ember-modifier';
import { assert } from '@ember/debug';
interface NeatSignature {
Args: {
Named: {
multiplier?: number;
};
Positional: [string];
}
}
function cleanup(instance: Neat) => {
if (instance.interval) {
clearInterval(instance.interval);
}
}
export default class Neat extends Modifier<NeatSignature> {
interval?: number;
constructor(owner: unknown, args: ArgsFor<NeatSignature>) {
super(owner, args);
registerDestructor(this, cleanup);
}
modify(
element: Element,
[lengthOfInput]: PositionalArgs<NeatSignature>,
{ multiplier }: NamedArgs<NeatSignature>
) {
assert(
`positional arg must be 'string' but was ${typeof lengthOfInput}`,
typeof lengthOfInput === 'string'
);
assert(
`'multiplier' arg must be a number but was ${typeof multiplier}`,
multiplier ? typeof multiplier === "number" : true
);
multiplier = modifier ?? 1000;
let updateTime = multiplier * lengthOfInput;
this.interval = setInterval(() => {
element.innerText =
`Behold, a type safe modifier moved after ${updateTime / 1000}s`;
}, updateTime)
}
}
See the Contributing guide for details.
This project is licensed under the MIT License.
Footnotes
-
As with autotracking in general, “changes” here actually means that the tracked property was set—even if it was set to the same value. This is because autotracking does not cache the values of properties, only the last time they changed. See this blog post for a deep dive on how it works! ↩