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:

• <Magento_Ui_module_dir>/view/base/web/templates/modal/modal-popup.html popup type template.
• <Magento_Ui_module_dir>/view/base/web/templates/modal/modal-slide.html slide type template.

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

Initialize the modal widget

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.

Options

The modal widget has the following options:

• appendTo
• autoOpen
• buttons
• clickableOverlay
• closeText
• customTpl
• focus
• innerScroll
• modalAction
• modalClass
• modalCloseBtn
• modalContent
• modalLeftMargin
• modalSubTitle
• modalTitle
• modalVisibleClass
• outerClickHandler
• parentModalClass
• popupTpl
• responsive
• slideTpl
• subTitle
• title
• trigger
• type

appendTo

The element where the modal should be added.

Type: String

Default value: body

autoOpen

Automatically open the modal window when the widget is initialized.

Type: Boolean

Default value: false

buttons

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();
    }
}]

clickableOverlay

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

Type: Boolean

Default value: true

closeText

The close button text.

Type: String

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

customTpl

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

Type: String

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

focus

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

Type: String

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

innerScroll

Modal scroll position.

Type: Boolean

Default value: false

modalClass

Custom classes for modal window.

Type: String

Default value: empty

modalAction

The selector for all the custom action buttons.

Type: String

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

modalCloseBtn

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

Type: String

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

modalContent

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

Type: String

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

modalLeftMargin

Sets a margin between slide modal windows.

Type: Number

Default value: 45

modalSubTitle

The modal subtitle element selector.

Type: String

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

modalTitle

The modal title element selector.

Type: String

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

modalVisibleClass

The class that is assigned to an opened modal.

Type: String

Default value: _show

parentModalClass

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

Type: String

Default value: _has-modal

outerClickHandler

The function that handles a click outside the modal window. If the outerClickHandler option is not specified, the closeModal() method is used for handling a click outside the modal window.

Type: Function

Default value: undefined

popupTpl

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

Type: String

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

responsive

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

Type: Boolean

Default value: false

slideTpl

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

Type: String

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

subTitle

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

Type: String

Default value: empty

title

Translated title for popup window.

Type: String

Default value: empty

trigger

The element that triggers the modal.

Type: String

Default value: empty

type

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

Type: String

Default value: popup

Methods

The modal widget has the following methods:

• closeModal()
• keyEventSwitcher()
• openModal()
• toggleModal()

openModal()

Open the modal window.

1
$('#css-selector').modal('openModal');

closeModal()

Close the modal window.

1
$('#css-selector').modal('closeModal');

keyEventSwitcher()

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

toggleModal()

Toggles the modal window.

Events

The modal widget is subscribed to the following events:

• closed
• opened

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
    }
});

closed

Called when the modal window is closed.

opened

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: jQuery.mage.__('Submit'),
                class: 'action'
            }]
        }}">
    <div class="content">
        Popup Content
    </div>
</div>

The following example shows a PHTML file using the script:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
<button id="button">
    <span><?= $block->escapeHtml(__('Click me')) ?></span>
</button>

<div id="modal">
    <div class="modal-body-content">
        <h2><?= $block->escapeHtml(__('Title')) ?></h2>
        <p><?= $block->escapeHtml(__('Content')) ?></p>
    </div>
</div>

<script type="text/javascript">
    require([
        "jquery",
        "Magento_Ui/js/modal/modal"
    ],function($, modal) {

        var options = {
            type: 'popup',
            responsive: true,
            title: 'Main title',
            buttons: [{
                text: $.mage.__('Ok'),
                class: '',
                click: function () {
                    this.closeModal();
                }
            }]
        };

        var popup = modal(options, $('#modal'));
        $("#button").click(function() {
            $('#modal').modal('openModal');
        });
    });
</script>

Result

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