ember-promise-modals

The better way to handle modals in your Ember.js apps.

> [!NOTE]
> ember-promise-modals was written and is maintained by Mainmatter and contributors.
> We offer consulting, training, and team augmentation for Ember.js – check out our website to learn more!

Compatibility

- Ember.js v3.28 or above
- Embroider or ember-auto-import v2

Installation

``
ember install ember-promise-modals
`

Usage

To use EPM in your project, add the target for the modals to your application.hbs:

`hbs

`

Then you can inject the modals service wherever you need and call its open method with a component class to render it as a modal.

`js
import { inject as service } from '@ember/service';
import ConfirmationModal from 'my-app/components/confirmation-modal';

export default class extends Component {
@service modals;

@action
async handleOpenModal() {
let modal = this.modals.open(ConfirmationModal);

// the instance acts as a promise that resolves with anything passed to the @close function
modal.then(results => {
// do something with the data
});

// so does awaiting it!
let results = await modal;

// you can also close the modal from outside
modal.close();
}
}
`

`hbs

Click Me!

`

$3

You can pass custom data into your rendered template like so:

`js
this.modals.open(FilePreviewModal, {
fileUrl: this.fileUrl,
});
`

All passed attributes can be accessed from the passed-in data object:

`hbs


`

`js
// components/file-preview.js
this.args.data.fileUrl; // or this.data.fileUrl in classic components
`

NOTE: By default, a close method is passed in your rendered component, in
order to trigger the "close modal" action. It can be called like so:

`hbs

Close
`

`js
// components/file-preview.js
this.args.close(results); // or this.close() in classic components
`

$3

This addon comes with a {{open-modal}} template helper which can be used to trigger modals from any templates. It accepts the similar arguments as the open method. It can be used to open a modal in a route, closing it automatically when navigating elsewhere.

`hbs
{{open-modal this.ConfirmationModalComponent (hash fileUrl=this.fileUrl) close=(fn this.save results)}}
`

Positional arguments mimick the open() method on the service:

- componentClass: An imported component class of the modal to render
- data: Pass additional context to the modal,
- options: Pass additional options to the modal

Named arguments:

- close is called asynchronously with the data returned by the modals @close action when it is closed

Animation

This addon uses CSS animations. You can either replace the
styles of this addon with your own
or adjust the defaults using CSS custom properties in your :root{}
declaration or in the CSS of any parent container of .

Available properties and their defaults can be found in the :root {} block inside the addons css.

By default, the animations are dropped when prefers-reduced-motion is
detected.

$3

To override the animation for a specific modal, an options object containing
a custom className can be handed to the .open() method.

`js
this.modals.open(
FilePreviwModal,
{
fileUrl: this.fileUrl,
},
{
// custom class, see below for example
className: 'custom-modal',
// optional: name the animation triggered by the custom css class
// animations ending in "-out" are detected by default!
// You most likely do not have to do this unless you absolutely
// can't have an animation ending in '-out'
animationKeyframesOutName: 'custom-animation-name-out',
// optional: a hook that is called when the closing animation of
// the modal (so not the backdrop) has finished.
onAnimationModalOutEnd: () => {},
},
);
`

`css
.custom-modal {
animation: custom-animation-in 0.5s;
opacity: 1;
transform: translate(0, 0);
}

/*
The .epm-out class is added to the parent of the modal when the modal
should be closed, which triggers the animation
*/
.custom-modal.epm-out {
animation: custom-animation-name-out 0.2s; / default out animation is 2s /
opacity: 0;
transform: translate(0, 100%);
}

/*
animation name has to end in "-out" to be detected by the custom animationend
event handler
*/
@keyframes custom-animation-name-out {
0% {
opacity: 1;
transform: translate(0, 0);
}
100% {
opacity: 0;
transform: translate(0, 100%);
}
}
`

The CSS animations which are applied by the custom CSS class _must_ end in
-out to make the animations trigger the modal removal.

#### Examples

Examples for custom animations and how to apply them can be found in the addon's
dummy application.

See the application.js controller
for how the modals are opened in your JavaScript actions and look at
app.css for the style definition of these
custom animations.

Accessibility

User can press the Esc key to close the modal.

EPM uses focus-trap internally
in order to handle user focus.

EPM will ensure to focus the first "tabbable element" by default.
If no focusable element is present, focus will be applied on the currently
visible auto-generated container for the current modal.

Focus Trap can be configured both on the modals service, and the individual
modal level when calling this.modals.open(). Global and local options are used
in that order, which means that local config take precedence.

To set global Focus Trap config that all modals inherit, override the default
Modals service by extending it, place it to app/services/modals.js, then
use the focusTrapOptions property:

`js
import BaseModalsService from 'ember-promise-modals/services/modals';

export default class ModalsService extends BaseModalsService {
focusTrapOptions = {
clickOutsideDeactivates: false,
};
}
`

Example for local Focus Trap option, when opening a specific modal:

`js
this.modals.open(
FilePreviewModal,
{ fileUrl: this.fileUrl },
{
focusTrapOptions: {
clickOutsideDeactivates: false,
},
},
);
`

To disable Focus Trap completely, set focusTrapOptions to null on the
modals service:

`js
import BaseModalsService from 'ember-promise-modals/services/modals';

export default class ModalsService extends BaseModalsService {
focusTrapOptions = null;
}
`

Or when opening a modal:

`js
this.modals.open(
FilePreviewModal,
{ fileUrl: this.fileUrl },
{
focusTrapOptions: null,
},
);
`

⚠️ _We strongly advise against doing this. This will in most cases worsen the
accessibility of modals for your users. Be very careful._

Testing

This addon provides a test helper function that reduces the timing for the CSS transitions to near zero to speed up your tests.

`js
import { setupPromiseModals } from 'ember-promise-modals/test-support';

module('Application | ...', function (hooks) {
// ...
setupPromiseModals(hooks);
// ...
});
``

Migration guide

See the Migration guide for details:

- From 0.x.x to 1.x.x about the replacement of ember-animated powered animations with CSS-based animations.
- From v4.x.x to v5.x.x about the removal of the PostCSS process.

Contributing

See the Contributing guide for details.

License

ember-promise-modals is developed by and © Mainmatter GmbH and contributors. It
is released under the MIT License.