Converting modals from legacy controllers to new DModal component API

:information_source: If you’re implementing a new Modal, check out the main docs here. This topic describes how to migrate an existing controller-based Modal to the new Component-based API.

In the past, Discourse used an Ember-Controller-based API for rendering modals. To invoke the modal, you would pass a string with the name of the controller to showModal(). Under the covers, this made use of Ember’s Route#renderTemplate API, which is deprecated in Ember 3.x and will be removed in Ember 4.x.

To allow Discourse to upgrade to Ember 4.x and beyond, we’ve introduced a new component-based API for modals. This new API embraces Ember’s ‘declarative’ design patterns, and aims to provide clean DDAU (data down actions up) semantics.

Step 1: Move Files

Move the controller JS file and the template file to the /components/modal directory. This makes them a ‘colocated component’ which can be imported just like any other JS module.

Step 2: Update the JS file

Then, update the component JS definition to extend from @ember/component instead of @ember/controller [1]. Remove the ModalFunctionality mixin and update any uses of its functions according to the table below:

Before After
flash() and clearFlash() Create a flash property in your component and pass it to the @flash argument of <DModal>. By default the alert will be styled with the alert class which is a copy of the ‘error’ class, but it can be overridden using the @flashType argument.
showModal() Import the showModal function from discourse/lib/show-modal
closeModal action Invoke the closeModal argument which is automatically passed into your component

Old-style Modal Controllers would live ‘forever’, which meant we had to manually cleanup state. With the new Component-based API, the component will be created and destroyed when the modal is shown/hidden. In many cases that means your old lifecycle hooks are no longer required.

If you still need some lifecycle-based logic, use this table:

Before After
onShow() Use standard Ember component lifecycle (init() or Ember modifier)
afterRender Use standard Ember component lifecycle (init() or Ember modifier)
beforeClose() create a wrapper around the @closeModal argument which is passed into your component. Pass a reference to your close wrapper into DModal like <DModal @closeModal={{this.myCloseModalWrapper}}>
onClose() Use standard Ember component lifecycle (willDestroy() or Ember modifier)

Step 3: Update the Template

Replace the <DModalBody> wrapper with <DModal>. Add some new attributes:

  • Pass through the new @closeModal argument
  • Add an explicit class. To match the old behaviour, take your controller filename and add -modal.

For example, if your modal controller was called close-topic.js, the new <DModal> invocation would look something like this:

<DModal @closeModal={{@closeModal}} class="close-topic-modal">

If the DModalBody invocation includes any other arguments, update them based on the table below:

Before After
@title="title_key" @title={{i18n "title_key"}}
@rawTitle="translated title" @title="translated title"
@subtitle="subtitle_key" @subtitle={{i18n "subtitle_key"}}
@rawSubtitle="translated subtitle" @subtitle="translated subtitle"
@class @bodyClass
@modalClass Use angle-bracket syntax with regular html attribute: <DModal class="blah">
@titleAriaElementId Use angle-bracket syntax with regular html attribute: <DModal aria-labelledby="blah">
@dismissable, @submitOnEnter, @headerClass Unchanged

If there was any footer content rendered after the old <DModalBody> component, use the new <:footer> named block to introduce it inside <DModal>. When using any named blocks, the body content should be wrapped in <:body></:body>. For example:

<DModal @closeModal={{@closeModal}}>
    Hello world, this is the content of the modal
    This is the footer content.
    A `.modal-footer` wrapper will be added automatically

Step 4: Update the showModal call sites

Previously, modals would be rendered using the showModal API, which would take a string (the controller name) and a number of opts. It would return an instance of the controller which could be manipulated:

import showModal from "discourse/lib/show-modal";

export default class extends Component {
  showMyModal() {
    const controller = showModal("my-modal", {
      title: "My Modal Title",
      modalClass: "my-modal-class",
      model: { topic: this.topic },
    controller.set("updateTopic", this.updateTopic);

To render new component-based Modals you should inject the ‘modal’ service (or access it using something like getOwner(this).lookup("service:modal")) and call the show() function.

show() takes a reference to the new Component class as the first argument. The only opt still supported is ‘model’, which can be used to pass all data/actions required for your Modal.

No reference to the component instance will be returned. Instead, show() returns a promise which will resolve when the modal is closed. The promise will resolve with any data which was passed to @closeModal.

import MyModal from "discourse/components/my-modal";
import { inject as service } from "@ember/service";

export default class extends Component {
  @service modal;

  showMyModal() {, {
      model: { topic: this.topic, updateTopic: this.updateTopic },

Alternatively, migrate to the declarative API described in the main DModal documentation.

The functionality of the old options can be replicated as follows:

Old showModal opt Solution
admin n/a for component - remove it
templateName n/a for components - remove it
title move to <DModal @title={{i18n "blah"}}>
titleTranslated move to <DModal @title="blah">. This could be computed based on data from model if needed
modalClass move to <DModal class="blah">
titleAriaElementId move to <DModal aria-labelledby="blah">
panels Use the <:headerBelowTitle> named block to implement tabs in your component (example)
model unchanged

Step 5: Tests

Any tests should largely remain the same. The most common issue are:

  • Modals no longer have a default class based on their name. Classes must be specified explicitely in the template (see beginning of Step 3)

  • The d-modal wrapper no longer persists in the DOM when the modal is closed. To check all modals are closed, use a check like assert.dom('.d-modal').doesNotExist()


Your modal should now work as it did before. To take further advantage of the new API, you may want to consider replacing showModal calls with a declarative strategy, and converting your Modal to be a Glimmer component.


Here are some example commits which demonstrate converting some of Discourse core’s modals to the new API:

  1. Classic Ember Components are recommended in this guide because they provided the easiest migration path from Ember Controllers. But for simple modals, or if you’re happy to spend some time refactoring, modern Glimmer components are the better choice. ↩︎

Last edited by @JammyDodger 2024-05-26T08:32:29Z

Check documentPerform check on document:

This looks really great. It gives me hope they I can convert my modals to ember 4. I only barely understand the ember code that I write, so writing documentation that I can understand is not easy. Thanks very much for this.


Thanks for the tutorial! Looking at the examples was highly useful. Had been able to fix my custom plugin modal broken in an hour.


I’m working on this conversion right now, but running into an issue:

Previously, our modal did not have a corresponding controller/JS definition, and we were able to show the modal through showModal($HBS_FILE_NAME). Since the new show() requires a component to be passed in, I need to introduce this JS definition (is this a correct assuption?).

I added something like:

import Component from '@glimmer/component';

export default class SomeModal extends Component {

  constructor() {
    console.log('Modal constructor')

and have the previous .hbs file (with required changes to DModal) both in the /components/modal directory with the same file name. When trying to render the modal (via getOwner(this).lookup("service:modal").show(SomeModal)), I see my constructor log printed in console, but the modal is not rendered.

Is there any other configuration needed in the controller/JS definition needed for this change? Any guidance would be much appreciated!

You don’t need it if you’re not adding any code.

You can have just the .hbs file.

discourse-templates, for example, doesn’t have a corresponding JS file for the modal handlebars template.

Did you adapt your handlebars template following the instructions?

Are there any errors in the console?


Thanks for the feedback! Huge :facepalm: on my end, I had moved files to the .../discourse/templates/components/modal dir, instead of .../discourse/components/modal. Things are working as expected now (with or without the .js controller), thank you!


Could you show me how to call showModal() from scrip inside a head_tag.html please? In my case I need to use

document.querySelector(".actions .double-button .toggle-like");

to catch the click event, check the condition and then show a custom modal.

1 Like

Really appreciate the effort you made here to document this so clearly, David!

I’ve all but managed to clear deprecations for 3.2 in an afternoon on our biggest plugin.


How do you now access an existing modal in core to modify it?

In the past I’ve used this (which no longer works):
api.modifyClass("controller:poll-ui-builder", {

In this particular case, that class name seems to be declared nicely and is unchanged.


Depending on what you need to modify, I think the best solution would be to use a PluginOutlet to inject your custom code, or a PluginOutlet Wrapper to replace/conditionally show the core implementation. (You can PR to add an outlet if its not available)

If you really want to use modifyClass it should be still possible, it’s just that the modal is a component now and its nested in components/modal so you would access it like:

api.modifyClass("component:modal/poll-ui-builder", {
   pluginId: "your-custom-plugin-id",

   // insert custom code