Modals
Modal windows are secondary content areas that allow a user to focus on a subtask without leaving the context of the current screen. They are displayed on top of the current screen and may contain a variety of content types.
Simple Modal Example
When to Use
- Use to alert, instruct, or assist the user in performing a specific task or to capture secondary information related to form elements on the primary page.
- Use when the action does not require its own page to complete.
- Use when there is a need for the user to focus on a specific action or message.
Variations
- Simple Modal (shown above)
- Critical Action Modal
- Simple Form Modal
- Locked Buttons Modal Example
Display & Interactions
Modals should appear in the center of the screen while masking the surrounding background.
Include a clear title that matches text link, icon or button used to access the modal. This may be excluded if the content is extremely concise (an error message, for example).
The modal should close when the user clicks the close icon in the upper right or clicks anywhere outside the modal window. A cancel button may also be used for more complex tasks. In complex tasks, consider using messaging to confirm the user’s intent when the user selects a close action or clicks outside of the modal. This will ensure that data is not lost by an unintended action.
Modals should span a minimum of 4 columns and a maximum of 10. This allows the user to always see the current page and maintain context of where they are in the application.
Modals should not exceed the height of the viewable space. If the content exceeds this height, consider separating the content into its own page or simplifying the content into smaller steps. If this is not possible, a scroll bar should appear. In this scenario, a fixed footer containing the actions may also be used.
Buttons
Limit the number of buttons appearing in a modal and consider using a single primary button, since the close icon can perform the close/cancel task simultaneously.
When including more than one button, position the buttons according to the guidelines in the Buttons component.
Variations
Critical Action Modal Example
Simple Form in Modal Example
Locked Buttons Modal Example
Developer Notes
A modal consists of two parts: the content and the button(s) which trigger opening the modal overlay. Modal content elements should be given a class of spark-modal. Inside of this outermost element should be an element with a class of spark-modal__scroll. This ensures that the modal is both centered and scrollable if its content does not fit entirely on the screen.
Inside of this should be an element with a class of spark-modal__content. Use the grid classes to size this element appropriately. Inside of this content container you should add a close button with a class of spark-modal__close. Clicking on this element or outside of the content area will hide the modal. A class of spark-modal__dismiss can also be set on anchors or buttons to be used to dismiss the Modal.
Any actionable buttons should be placed inside of an element with a class of spark-btn-group. They will be right-aligned on desktop and justified on mobile.
When using button elements, it is important to provide a type attribute so that buttons behave as expected, especially if a form is integrated into the Modal. Refer to the Simple Form in Modal and Complex Form in Modal with Locked Buttons examples below to see how you could approach forms and buttons in a Modal.
Use of the modal requires a Javascript helper. It can be instantiated using new Spark.Modal(el) or $(el).sparkModal(), and the following options may be passed:
| Name | Type | Default | Description |
|---|---|---|---|
| onBeforeOpen | function | noop() | A callback function run before the popover opens. |
| onBeforeClose | function | noop() | A callback function run before the popover closes. |
| onAfterOpen | function | noop() | A callback function run after the popover opens. |
| onAfterClose | function | noop() | A callback function run after the popover closes. |
For all available methods and full API, refer to the component code on Bitbucket.
When creating the modal, there are two options for which element to pass: a clickable element that references a modal through a [data-modal] attribute, or an element with the spark-modal class.
You may programmatically call the open and close methods to toggle the visibility of the modal. If a modal is created without using a clickable element, these methods will be the only way to open that modal.
It is important to place the .spark-modal element as close to the top-level <body> tag as possible. Nested modals can face z-index issues.`
Simple Modal
Error Messaging
Simply add an instance of the Message Component to include an error, info or warning message in a modal.
Simple Form in Modal
Complex Form in Modal with Locked Buttons
For more complex modals, the header, body and footer content should be separated. This allows for the header and footer to be locked to the top and bottom of the page on small screens. Add a header by using the class spark-modal__header, and a footer using the class spark-modal__footer.
Although there is padding on the modal body content by default, use the spark-modal__full-width-content class to have a block align to both edges of the modal window.
Accessibility Notes
The Spark Modal component has been developed with accessibility in mind and while this is implemented within the provided component code, it is important to verify that any additional elements and components added into the modal are accounting for the use of screen-readers and other assistive devices.
With regards to what is included, when the modal is fired, keyboard navigation will be limited to elements that are able to receive keyboard focus. This includes the Close button that has a tab-index defined as it does not have an href attribute. Please refer to the examples in the Guidelines and Developer tabs to see how this has been implemented.
If focusable elements are added to the Modal dynamically prior to or after it has been opened, the number of focusable elements needs to be re-parsed to ensure that keyboard tabbing accounts for these new elements. A parseFocusableElements method has been made available for this purpose.