百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
E

ember-modal-dialog

> 编程语言
开源

用于实现模态对话框的 ember-cli 插件

387 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

用于实现模态对话框的 ember-cli 插件

Ember Modal Dialog

Regarding the Status of this Addon

A lot has happened in browser APIs, the JS ecosytem, and in the Ember ecosystem since this addon was created.

Most notably, all major browsers have added support for the HTML dialog element. This effectively delivers the core use case for this addon as a browser API. It is not syntax-compatible of course, so adopting it requires learning the new element and its programmatic API and using it as appropriate for your situation.

In the Javascript ecosystem, tether.js has reached the end of its life, being succeeded by popper and now by floating-ui as the most common solution for positioning a DOM element relative to another element. Our experience is that floating-ui works great in conjunction with Ember's modifiers. While there are addons that wrap it, like ember-velcro, we have found that using it directly does the job quite well.

In the Ember ecosystem, addon authors are transitioning addons to support modern versions of Ember and to become v2 addons. This addon has three dependencies that are either unsupported or poorly supported: ember-tether, liquid-wormhole, and liquid-tether.

Having contemplated these changes, we won't be investing in ongoing development of this addon, and are migrating away from it in our own projects. We will still review and accept PRs for bug fixes and compatibility, but we encourage you to move on.

Overview

The ember-modal-dialog addon provides components to implement modal dialogs throughout an Ember application using a simple, consistent pattern.

Unlike some other modal libraries for Ember, ember-modal-dialog uses solutions like ember-wormhole to render a modal structure as a top-level DOM element for layout purposes while retaining its logical position in the Ember view hierarchy. This difference introduces a certain elegance and, dare we say, joy, into the experience of using modals in your app. For more info on this, see the "Wormhole" section below.

Table of Contents

  • Ember Modal Dialog
    • Table of Contents
    • Live Demo and Test Examples
    • Including In An Ember Application
    • Upgrading
    • Controller-bound Usage
    • Routable Usage
    • Configurable Properties
      • modal-dialog
        • Tethering
        • Animation
      • Optional Dependencies
    • Which Component Should I Use?
    • Positioning
      • Caveats
    • Wormholes
    • Configuring the Modal Root Element Id
    • Configuring Styles
    • Keyboard shortcuts
    • iOS
    • Custom Modals
    • Using as a nested addon
    • Compatibility & Dependencies
    • Additional Resources
    • Contributing
    • Credits

Live Demo and Test Examples

View a live demo here: http://yapplabs.github.io/ember-modal-dialog/

Test examples are located in tests/dummy/app/templates/application.hbs and can be run locally by following the instructions in the "Installation" and "Running" sections below.

Including In An Ember Application

Here is the simplest way to get started with ember-modal-dialog:

bash
ember install ember-modal-dialog

Then import the CSS files

app.css

css
@import "ember-modal-dialog/ember-modal-structure.css";
@import "ember-modal-dialog/ember-modal-appearance.css";

If you’re using SASS then just import the CSS slightly differently

app.scss

scss
@import "ember-modal-dialog/ember-modal-structure";
@import "ember-modal-dialog/ember-modal-appearance";

application.hbs

htmlbars
{{#modal-dialog}}
  Oh hai there!
{{/modal-dialog}}

Upgrading

Earlier versions of ember-modal-dialog required ember-cli-sass and an app.scss file to import styling.

Please be aware this is no longer the case.

Existing applications should continue to work correctly but if you were using ember-cli-sass solely due to ember-modal-dialog it might be worthwhile removing ember-cli-sass completely and just importing the styles directly into app.css instead, as shown above.

Controller-bound Usage

Here is a more useful example of how to conditionally display a modal based on a user interaction.

Template

htmlbars
Toggle Modal

{{#if isShowingModal}}
  {{#modal-dialog
      onClose=(action "toggleModal")
      targetAttachment="center"
      translucentOverlay=true
  }}
    Oh hai there!
  {{/modal-dialog}}
{{/if}}

Controller

javascript
import Controller from '@ember/controller';

export default Controller.extend({
  isShowingModal: false,
  actions: {
    toggleModal() {
      this.toggleProperty('isShowingModal');
    }
  }
});

Routable Usage

To have a modal open for a specific route, just drop the {{modal-dialog}} into that route's template. Don't forget to have an {{outlet}} on the parent route.

Configurable Properties

modal-dialog

The modal-dialog component supports the following properties:

Property Purpose
hasOverlay Toggles presence of overlay div in DOM
translucentOverlay Indicates translucence of overlay, toggles presence of translucent CSS selector
onClose The action handler for the dialog's onClose action. This action triggers when the user clicks the modal overlay.
onClickOverlay An action to be called when the overlay is clicked. If this action is specified, clicking the overlay will invoke it instead of onClose.
clickOutsideToClose Indicates whether clicking outside a modal without an overlay should close the modal. Useful if your modal isn't the focus of interaction, and you want hover effects to still work outside the modal.
renderInPlace A boolean, when true renders the modal without wormholing or tethering, useful for including a modal in a style guide
overlayPosition either 'parent' or 'sibling', to control whether the overlay div is rendered as a parent element of the container div or as a sibling to it (default: 'parent')
containerClass CSS class name(s) to append to container divs. Set this from template.
containerClassNames CSS class names to append to container divs. If you subclass this component, you may define this in your subclass.)
overlayClass CSS class name(s) to append to overlay divs. Set this from template.
overlayClassNames CSS class names to append to overlay divs. If you subclass this component, you may define this in your subclass.)
wrapperClass CSS class name(s) to append to wrapper divs. Set this from template.
wrapperClassNames CSS class names to append to wrapper divs. If you subclass this component, you may define this in your subclass.)
animatable A boolean, when true makes modal animatable using liquid-fire (requires liquid-wormhole to be installed, and for tethering situations liquid-tether. Having these optional dependencies installed and not specifying animatable will make animatable=true be the default.)

Tethering

If you specify a tetherTarget, you are opting into "tethering" behavior, and you must have either ember-tether or liquid-tether installed.

Property Purpose
tetherTarget Element selector or element reference for that serves as the reference for modal position

We use the amazing Tether.js library (via ember-tether) to let you position your dialog relative to other elements in the DOM.

* Please see Hubspot Tether for usage documentation.

When in a tethering scenario, you may also pass the following properties, which are passed through to Tether:

Property Purpose
attachment Delegates to Hubspot Tether*
targetAttachment Delegates to Hubspot Tether*
tetherClassPrefix Delegates to Hubspot Tether*
offset Delegates to Hubspot Tether*
targetOffset Delegates to Hubspot Tether*
constraints Delegates to Hubspot Tether*

Animation

This component supports animation when certain addons are present (liquid-wormhole, liquid-tether).

Detection is be automatic. To opt out of using animatable features when you have these liquid-* addons installed, pass animatable=false.

When in an animatable scenario, you may also pass the following properties, which are passed through to liquid-wormhole or liquid-tether:

Property Purpose
stack Delegates to liquid-wormhole/liquid-tether

Optional Dependencies

Dependency Documentation
ember install ember-tether Docs
ember install liquid-wormhole Docs
ember install liquid-tether Docs
ember install liquid-fire Docs

Which Component Should I Use?

Various modal use cases are best supported by different DOM structures. Ember Modal Dialog's modal-dialog component provides the following capabilities:

  • modal-dialog without passing a tetherTarget: Uses ember-wormhole to append the following parent divs to the destination element: wrapper div > overlay div > container div

This can be customized (see overlayPosition).

  • modal-dialog, with a tetherTarget provided: Uses ember-tether to display modal container div. Uses ember-wormhole to append optional overlay div to the destination element. Requires separate installation of ember-tether dependency.

Positioning

With the default CSS provided, your modal will be centered in the viewport. By adjusting the CSS, you can adjust this logic.

Pass a tetherTarget in order to position our modal in relation to the target and enable your modal remain positioned near their targets when users scroll or resize the window.

Use attachment and targetAttachment properties to configure positioning of the modal dialog near its target. Ember Modal Dialog uses the syntax from Hubspot Tether for these properties: "top|middle|bottom left|center|right|elementCenter"... e.g. 'middle left'

To enable this behavior, install ember-tether as a dependency of your ember app.

ember install ember-tether

Then pass a selector as tetherTarget for the modal you wish to position this way:

htmlbars
{{#modal-dialog
    tetherTarget='#target-element-id'
    targetAttachment='middle right'
    attachment='middle left'
}}
  I am a modal that will remain tethered to the right of the element with id 'target-element-id'
{{/modal-dialog}}

Caveats

Event delegation originating from content inside ember-tether blocks will only work for Ember apps that use Ember's default root element of the body tag. This is because, generally speaking, the Hubspot Tether library appends its positioned elements to the body element.

If you are not overriding the default root element, then don't worry and carry on. ember-tether will work just fine for you.

Wormholes

Disp

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言