Modal сomponent

This topic describes the modal UI component.

The Modal UI component implements a secondary window that opens on top of the main window. It uses the modal widget.

Similar to the widget’s configuration, the component’s configuration allows you to set the window type and action buttons behavior (including linking action buttons to methods of the other UI components).

The Modal component can be used for both Admin panel and storefront.

For recommendations about modal windows usage from the UX point of view, see the corresponding topic in the Magento Admin pattern library.

Structure

The modal UI component comprises the following files:

  • JS component: <Magento_Ui_module_dir>/view/base/web/js/modal/modal-component.js
  • Template: <Magento_Ui_module_dir>/view/base/web/templates/modal/modal-component.html

Options

Component’s options are set in the configuration .xml file as follows:

 <modal name="test_modal">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <!-- Configurable options are specified here -->
            <item name="%option1%" xsi:type="%type%">%value%</item>
            <item name="%option2%" xsi:type="%type%">%value%</item>
            ...
        </item>
    </argument>
</modal>

The modal component uses general configuration options, similar to other UI components. However, it uses the following specific options as well:

Modal options
state

Set the state of the modal window: true for open.

Type: Boolean

Required?: Optional

Default value: false

options

Configuration for the modal widget. Passed to the widget initialization as is.

Type: Object

Required?: Optional

Default value: {}

title

The title of the modal window. Set as follows:

<item name="options" xsi:type="array">
    <item name="title" xsi:type="string">%window_title%</item>
</item>

Type: String

Required?: Optional

Default value: ''

subTitle

The subtitle of the modal window. Set as follows:

<item name="options" xsi:type="array">
    <item name="title" xsi:type="string">%window_subtitle%</item>
</item>

Type: String

Required?: Optional

Default value: ''

type

The type of the modal window. Can be one of the following: slide or popup. Set as follows:

<item name="options" xsi:type="array">
    <item name="type" xsi:type="string">%slide|popup%</item>
</item>

Type: String

Required?: Optional

Default value: slide

buttons

The action buttons of the modal window.

Type: Array Required?: Optional Default value: []

text

The button label.
Set as follows:

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="text" xsi:type="string">%label%</item>
         </item>
    </item>
</item>

Type: String

Required?: Optional

Default value: Undefined

class

The CSS class for the button.
Set as follows:

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="class" xsi:type="string">%class%</item>
         </item>
    </item>
</item>

Type: String

Required?: Optional

Default value: Undefined

actions

Button actions. On button click, actions are performed in the same order as they are specified in config.
Set as follows:

<item name="options" xsi:type="array">
    <item name="buttons" xsi:type="array">
         <item name="%button_number%" xsi:type="array">
             <item name="actions" xsi:type="string">
                <--! Action that calls the method of the other UI component -->
                <item name="%action_number%" xsi:type="array">
                    <item name="targetName" xsi:type="string">%component_which_performs_action%</item>
                    <item name="actionName" xsi:type="string">%method_of_target_component%</item>
                </item>
                <--! Action that calls the method of the modal component -->
                <item name="%next_action_number%" xsi:type="array">%method_of_modal_component%</item>
             </item>
         </item>
    </item>
</item>

Type: Object

Required?: Optional

Default value: Undefined

onCancel

Action (method name), that is performed on canceling interactions: pressing Esc, clicking outside the modal window, or clicking the 'X' (close) icon.

Type: String

Required?: Optional

Default value: closeModal

Example of the Modal component configuration

The following sample is an example of the configuration for a simple modal window containing one text field and a standard set of action buttons (Cancel, Clear, Done):

<modal name="test_modal">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="onCancel" xsi:type="string">actionCancel</item>
            <item name="options" xsi:type="array">
                <item name="buttons" xsi:type="array">
                    <item name="0" xsi:type="array">
                        <item name="text" xsi:type="string">Cancel</item>
                        <item name="class" xsi:type="string">action-secondary</item>
                        <item name="actions" xsi:type="array">
                            <item name="0" xsi:type="string">actionCancel</item>
                        </item>
                    </item>
                    <item name="1" xsi:type="array">
                        <item name="text" xsi:type="string">Clear</item>
                        <item name="class" xsi:type="string">action-secondary</item>
                        <item name="actions" xsi:type="array">
                            <item name="0" xsi:type="array">
                                <item name="targetName" xsi:type="string">${ $.name }.testField</item>
                                <item name="actionName" xsi:type="string">clear</item>
                            </item>
                        </item>
                    </item>
                    <item name="2" xsi:type="array">
                        <item name="text" xsi:type="string">Done</item>
                        <item name="class" xsi:type="string">action-primary</item>
                        <item name="actions" xsi:type="array">
                            <item name="0" xsi:type="string">actionDone</item>
                        </item>
                    </item>
                </item>
            </item>
        </item>
    </argument>
    <field name="testField">
        <argument name="data" xsi:type="array">
            <item name="config" xsi:type="array">
                <item name="label" xsi:type="string">test field</item>
                <item name="formElement" xsi:type="string">input</item>
                <item name="visible" xsi:type="boolean">true</item>
            </item>
        </argument>
    </field>
</modal>

<button name="modal_button">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="title" xsi:type="string">Open modal</item>
            <item name="actions" xsi:type="array">
                <item name="0" xsi:type="array">
                    <item name="targetName" xsi:type="string">${ $.parentName}.test_modal</item>
                    <item name="actionName" xsi:type="string">openModal</item>
                </item>
            </item>
        </item>
    </argument>
</button>

Public API (JS)

  • actionCancel(): returns all modal’s child components to the state they had on modal open and closes the modal window.
  • actionDone(): validates the changes in the modal’s child components and, if valid, closes the modal.
  • closeModal(): closes the modal window.
  • openModal(): opens the modal window.
  • setPrevValues(elem): returns all elem’s child components to the state they had on modal open.
  • setTitle(): sets modal title.
  • setSubTitle(): sets modal sub title.
  • toggleModal(): toggles the modal window state (open/close).