Modal widget

The Magento modal widget implements a secondary window that opens on top of the main window. It contains the overlay and modal content. The modal widget configuration enables the following:

  • Configuring as popup or slide
  • Controlling stack of modal widgets
  • Setting buttons for action bar

The modal widget source is <Magento_Ui_module_dir>/view/base/web/js/modal/modal.js.

The widget uses the following templates:

The design patterns for the modal pop-up windows in the Admin are described in the Magento Admin Pattern Library, the Slide-out Panels, Modal Windows, and Overlays topic.

To initialize the widget in your script, use the following general notation:

1
2
3
4
5
$('#modal_content').modal({
    <option1>: <value1>,
    <option2>: <value2>,
    ...
});

For details about how to initialize the widget in a.phtml template, refer to the JavaScript initialization topic.

The modal widget has the following options:

The element where the modal should be added.

Type: String

Default value: body

Automatically open the modal window when the widget is initialized.

Type: Boolean

Default value: false

Array of buttons for action pane.

Type: Array

Structure:

1
2
3
4
5
buttons: [{
    text: '',
    class: '',
    click: function () {} //handler on button click
}]

Default value:

1
2
3
4
5
6
7
buttons: [{
    text: $.mage.__('Ok'),
    class: '',
    click: function () {
        this.closeModal();
    }
}]

Close the modal window when a user clicks on the overlay.

Type: Boolean

Default value: true

The close button text.

Type: String

Default value: $.mage.__('Close')

The template file that is used as content for the custom modal type.

Type: String

Default value: ui/template/modal/modal-custom.html

Selector to focusing when a modal window opens or ‘none’ if focusing is not necessary.

Type: String

Default value: [data-role="closeBtn"]

Modal scroll position.

Type: Boolean

Default value: false

Custom classes for modal window.

Type: String

Default value: empty

The selector for all the custom action buttons.

Type: String

Default value: [data-role="action"]

The selector for all the elements that can close the modal.

Type: String

Default value: [data-role="closeBtn"]

The selector for element that is used for the modal’s content.

Type: String

Default value: [data-role="content"]

Sets a margin between slide modal windows.

Type: Number

Default value: 45

The modal subtitle element selector.

Type: String

Default value: [data-role="subTitle"]

The modal title element selector.

Type: String

Default value: [data-role="title"]

The class that is assigned to an opened modal.

Type: String

Default value: _show

The class that is assigned to parent when the modal is opened.

Type: String

Default value: _has-modal

The template file that is used as content for the popup modal type.

Type: String

Default value: ui/template/modal/modal-popup.html

Turn popup modal window to slide panel on small screens. Available if the type option is set to ‘popup’.

Type: Boolean

Default value: false

The template file that is used as content for the slide modal type.

Type: String

Default value: ui/template/modal/modal-slide.html

Translated subTitle for the popup window that will be appended to the title.

Type: String

Default value: empty

Translated title for popup window.

Type: String

Default value: empty

The element that triggers the modal.

Type: String

Default value: empty

The type of window: ‘popup’ or ‘slide’.

Type: String

Default value: popup

The modal widget has the following methods:

Open the modal window.

Close the modal window.

Listens for key events and calls handler function if it exists.

Toggles the modal window.

The modal widget is subscribed to the following events:

You can listen to these events in two ways:

Use jQuery’s on function:

1
2
3
4
var modal = $('#modal_content').modal({...});
modal.on('modalclosed', function () {
    // Do some action when modal closed
});

Or assign a callback as a property when creating a modal instance:

1
2
3
4
5
6
$('#modal_content').modal({
    ...
    closed: function (){
       // Do some action when modal closed
    }
});

Called when the modal window is closed.

Called when the modal window is opened.

Keyboard navigation

  • the ESC key: close the current modal window
  • the TAB key: set focus to the next focusable element (looped inside the modal window)
  • the SHIFT+TAB keys combination: set focus to the previous focusable element (looped inside the modal window)

Code sample

The following example shows how to initialize the modal widget and pass options during the initialization.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<button type="button" class="action" data-trigger="trigger">
    <span data-bind="i18n: 'Click Here'"></span>
</button>
<div data-bind="mageInit: {
        'Magento_Ui/js/modal/modal':{
            'type': 'popup',
            'title': 'Popup title',
            'trigger': '[data-trigger=trigger]',
            'responsive': true,
            'buttons': [{
                text: $.mage.__('Submit'),
                class: 'action'
            }]
        }}">
    <div class="content">
        Popup Content
    </div>
</div>

Result

The result is a modal and a button (Click Here) that opens the modal.

Modal Widget