Modal

Example

<vega-modal 
    size="400" 
    backdrop="static"
    open=false
    id = "my-modal">
    <p>This content will appear in the modal.</p>

    <div>
        <vega-button data-dismiss="modal">
            Close
        </vega-button>
    </div>
</vega-modal>

<vega-button data-target="my-modal">Launch modal</vega-button>

Handle Close Example

<vega-modal id="handle-close-modal-template" modal-title="Demo modal">
    <div class="v-font-h6 v-text-secondary v-mb-size-12">Try to click the close button on top right.</div>
</vega-modal>
<vega-button data-target="handle-close-modal-template">Launch modal</vega-button>

    const modal = document.querySelector('#handle-close-modal-template');
    modal.handleClose = () => {
        if (confirm('Confirm you will close the modal')) {
            return true; // Will close the modal if the callback return true, otherwise do nothing
        }
    };

Usage

The vega-modal is a dialogue window which appears on top of the parent screen. Unlike pop-up windows, these disable the parent screen, but keep it visible. The modal window may open when a user presses a button on the page which triggers this action, and a user must interact with this screen before returning to the main/parent screen.

Modal windows are used when it becomes necessary to interrupt the user’s attention for an action that needs to be taken.

Properties

All Parameters

<vega-modal
    size="any number | { [key in default|S|M|L|XL]?: any number }"
    backdrop="static|''"
    open=true|false
    animation=true|false
    modal-title=""
    backdrop-color="default|semi|none"
    is-vertically-center=true|false
    show-close-button=true|false
>
    <!--Content-->
</vega-modal>

For more details, view in Storybook.

Note: Vega modal has a default maximum width dependent on screen size. If size exceeds the maximum width, the maximum modal width will be used instead.

Note re: scrolling: If the modal content is too long, a scroll bar will appear and the body cannot be scrolled. For iOS, the body content of the scrolling modal will occasionally appear to scroll. This problem also appears in:

• Bootstrap
• Material

Using Slots

You may use slots to set the modal header, content, and footer.

Example:

<vega-modal>
    <div slot='modal-title'></div>
	<div slot='modal-content'></div>
	<div slot='modal-footer'></div>
</vega-modal>

Using Data Attributes

You may use the vega-modal without JavaScript by making use of the data-target data attribute. Note that the data-target id must match the id of the vega-modal.

<vega-button data-target="modalID">Launch modal</vega-button>

Calling modals via JavaScript

You may use a single line of JavaScript to call a modal:

document.getElementById('my-modal').modal(option);

You may hide a modal using .modal("hide") or show it using .modal("show").

Both methods return to the caller before the modal has been shown or hidden.

Events

Vega modals dispatch two events:

• vegaOpen is dispatched when the modal is opened and rendered.

document.getElementById("modal_id").addEventListener("vegaOpen", (e) => { console.log(e.currentTarget.value)
})

• vegaClose is dispatched when the modal is closed.

document.getElementById("modal_id").addEventListener("vegaClose", (e) => { console.log(e.currentTarget.value)
})

Accessibility

• Ensures every id attribute value is unique.
• Ensure that text spacing set through style attributes can be adjusted with custom stylesheets.
• Ensures buttons have discernible text.
• Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds.
• Ensures every id attribute value is unique.
• Nested interactive controls are not announced by screen readers.

Best Practices

• As a general rule, modals are best used when there is input required from a user that is necessary to continue performing the action on the main screen.
• It is wise to avoid using modal windows for error, success, or wait states when processing an action; they are intrusive and add no value to the interaction.
• While they are sometimes used for loading actions, this is not a recommended use; instead it’s better to provide that information inline and on the screen itself.
• Modals should be primarily used for user-initiated interactions, and not generated by the system or they can create a jarring experience for the user, and in many cases they are considered annoying.
• When using modal windows, use clear descriptive language to explain the purpose of the window, and with clear instructions to the user regarding the actions they need to take to dismiss the window. This information should be contained directly in the modal window.
• If simply dismissing the modal is a possibility, ensure that there are clear controls for doing so, such as a closing “X” button and/or language stating “Dismiss” or “Cancel.” It is also wise to support clicking outside the modal to close it.
• Place modal windows directly in the sight of the user, so that they are directly in focus. Keyboard focus also needs to be moved to this window, and users should be able to continue using the site using a keyboard and without a pointing device. Allow the “Escape” key to dismiss the modal.
• Do not nest modals within other modals; this creates a jarring and disorienting experience for the user.

Do

Don't