Aurelia Dialog Release Candidate

Posted by AureliaEffect on April 27, 2017

Thanks to the hard work of Aurelia Core Team members, Strahil Kazlachev and Patrick Walters, we're proud to announce the Aurelia Dialog v1 Release Candidate.


We have an exciting release today that's been in the making for quite some time! Aurelia Dialog is hitting it's 1.0 Release Candidate. Below we've provided a list of all the new features and enhancements as well as a list of breaking changes. Finally, at the bottom you will find an upgrade path from our alpha release.

New Features and Enhancements

Keyboard Settings

We've created dialog settings that can be bound to keyboard events. Currently only the Enter key, Escape key, or both are supported. Custom handlers and/or custom keys will be supported in future releases. This greatly improves the developer's ability to customize the user experience.

Closing All Open Dialogs

We've added the ability for the developer to close all open dialogs. This can be helpful, for example, when many dialogs are open and the user initiates a route change.

Promise Handling

Previously, when a developer opened a dialog, it returned a promise and when the dialog was cancelled, we forced the developer to check every time whether the result was cancelled or not. We've now added the ability for the developer to define if they would instead like for the promise to reject in cancel-like events. This means that each time the cancel event is fired the developer needs to handle the rejection, else the error will propogate and be thrown in the browser's console.


In general, we've tried to consolidate the settings that were available to the developer. Over time many settings were added, some of which had conflicting behavior, so we took the time to document all intended behaviors and refactor them into more meaningful settings.

Breaking Changes

New Settings

For all settings below, we are showing the setting name on the left and the default value on the right:

  • host = document.querySelector('body') - Defines where the dialog is inserted in the DOM. Defaults to the body tag.
  • childContainer = undefined - Until now the container for the dialog was created in the .open() call, from the root container. With this new setting you can provide your own preconfigured container per .open() call. This enables tons of flexibility - a custom renderer per dialog, integrating a dialog with a custom element, etc. - so the developer can use the custom element container to create a new child container and pass it to .open().
  • keyboard = undefined - Can be used to override behavior such as when the enter key is pressed.
  • overlayDismiss = undefined - Determines whether clicking on the overlay (the area outside of the dialog) invokes the close method. If left unset, defaults to the existing lock setting.
  • rejectOnCancel = false - When a dialog is cancelled, should it reject the promise?

DialogService Methods

  • .closeAll() - Closes all open dialogs
  • .open() - Clearly defined the behavior for what happens when .canActivate returns/resolves to false

DialogController Changes

  • .ok()/.cancel()/.close() - Clearly defined the behavior for what happens when .canDeactivate returns/resolves to false

UxDialogHeader - ux-dialog-header

  • showCloseButton - A bindable property indicating whether to show a close button in the dialog.

Prefix Schema - ai-/Ai changes to ux-/Ux

  • css classes
    • .ai-dialog-open => .ux-dialog-open
  • elements
    • <ai-dialog-container> => <ux-dialog-container>
    • <ai-dialog-overlay> => <ux-dialog-overlay>
  • custom elements
    • <ai-dialog> => <ux-dialog>
    • <ai-dialog-header> => <ux-dialog-header>
    • <ai-dialog-body> => <ux-dialog-body>
    • <ai-dialog-footer> => <ux-dialog-footer>
    • AiDialog => UxDialog
    • AiDialogHeader => UxDialogHeader
    • AiDialogBody => UxDialogBody
    • AiDialogFooter => UxDialogFooter


  • .openAndYieldController() - This method has been removed and now maps to the new .open() method via .open().then(...).
  • .open() - Refactored - The old behaviour maps to .open().whenClosed(...).
    • The returned promise resolves when the dialog is opened with a DialogOpenResult
    • The returned Promise has an additional .whenClosed() method. It has the same signature as .then. Use it when you want to follow when the dialog gets closed.


  • viewModel - removed property - previously undocumented
  • view - removed property - previously undocumented
  • viewSlot - removed property - previously undocumented