Modal widget

Overview

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 Magento 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:

$('#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:

• autoOpen
• buttons
• clickableOverlay
• focus
• innerScroll
• modalClass
• modalLeftMargin
• responsive
• title
• type

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:

buttons: [{
    text: '',
    class: '',
    click: function() {} //handler on button click
}]

Default value:

buttons: [{
    text: 'Ok',
    class: '',
    click: function() {
        this.closeModal();
    }
}]

clickableOverlay

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

Type: Boolean

Default value: true

focus

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

Type: String

Default value: ''

innerScroll

Modal scroll position.

Type: Boolean

Default value: false

modalClass

Custom classes for modal window.

Type: String

Default value: empty

modalLeftMargin

Sets a margin between slide modal windows.

Type: Number

Default value: 45

responsive

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

Type: Boolean

Default value: false

title

Translated title for popup window.

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()
• openModal()

openModal()

Open the modal window.

closeModal()

Close the modal window.

Events

The modal widget is subscribed to the following events:

• closed
• opened

closed

Called when the modal window is closed.

opened

Called when the modal window is opened.

always

….

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)