Design
Web component
Is documented
The component is fully documented
Status
Status
Healthy
Figma component
Includes a link to a Figma component that has been imported to Supernova
Principles
Use when
- input needs to be obtained from the user and additional information regarding a process needs to be displayed
- display feature announcements or important (critical) information related to a process/action.
- operations requiring user confirmation (hard delete, archive, duplicate, etc.) need to be displayed
- complex process flows need to be shown by splitting them down into steps
- providing supplemental tasks required by the underlying page.
Don't use when
- display large flows which can also be displayed in a page layout
- long-form lists are preferred to be used
- error or success notifications are wanted to be displayed, use notification instead.
Structure
- Header
- Body
- Footer
Properties
Types
Transactional modal are used to validate user decisions or to get secondary confirmation from the user. This modal type can contain form inputs to complete related actions.
Passive modals are for when the user needs to confirm or obtain information in their current workflow, listing the implications for the current state and potential outcomes. They do not contain any actions other than approving or denying.
Destructive modals warn users about potential destructive outcomes if they proceed, and often serve as confirmation for actions that could cause significant data loss if accidentally triggered.
Acknowledgment modal is used to convey information to the user. It does not contain any actions.
Process modals indicate the completion of a process related to that action. They can be used for import, export, and sending operations.
Positioning
When the modal is opened, they center the page horizontally. Vertically, they align on the page with a 40px margin.
Sizing
The modal component has 3 sizes: Small, default, and large. These 3 sizes should be used based on their intended purpose, not always for responsiveness.
The small size is intended for devices with a screen width below 600px when the application is used as a web app. The default size is a universal size suitable for all dimensions. The large size should be used primarily for actions involving large amounts of data.
Behavior
Interaction
The way of accessing the modal is a user action. Typically, modals are triggered by buttons.
Modals also contain nested components, thereby encapsulating all interaction points carried by the other components.
Scrolling
The height of the modal should match the content it contains within the body. However, this height should be scrollable within the page.
If the modal height exceeds the height of the current viewport, the modal container should be fully scrollable through the page. In other words, only the modal body itself should not be scrollable within.
Additionally, the background page should remain stationary relative to the modal during scrolling. If the footer remains fixed, filling out forms or readability in long body lists and narrow viewports will become difficult.
Do
Modal body should not have be fixed.
Don't
The header and footer cannot be fixed when the modal is not fitted within the viewport.
Validation
Especially in transactional modals, there may be components requiring user input (such as form inputs). If a form input list is used in this modal, default values should be provided in the context.
Errors should be checked and displayed during data entry without waiting for the user to confirm or close the modal. While doing this, we should also avoid showing errors with each keyboard input, as it can affect performance and annoy the user.
Close & Dismiss
The options for closing or dismissing modals vary depending on the context. However, when considering a basic modal, it can be closed using the "close" or "cancel" buttons located in the footer. Alternatively, clicking anywhere on the overlay background where the modal is situated can also close/dismiss it. It’s also possible with ESC (escape) key.
However, this should not always be applicable; for instance, in cases like transactional modals where user input is required and data has been previously entered, this feature should be disabled. Pay attention to the context when defining these rules.
Overlaying
Modals open on a transparent background to indicate the main page cannot be accessed temporarily.
Nested components
There are main nested components to be used within the body, and they assist in creating or conveying the content in the modal.
Buttons
Buttons in a modal, located in the footer as primary and secondary buttons, support interactions such as completing or confirming processes. For tertiary actions, like 'later' or 'skip,' ghost buttons are recommended.
Do
While grouping the buttons as a group, the tertiary button should be separated and left-aligned.
Don't
For clarity, the primary and secondary buttons are grouped together to keep related actions together.
Form inputs
Form inputs are used when an action related to a record needs to be added or executed within a different flow. They are primarily used in transactional modal types and should fit the modal's width.
Implications
Implications list the results and outcomes that follow the confirmation of an action. They must be used to warn the user about the next steps and explain the results of a related action.
Do
When listing items in implication, use a bulleted list.
Notifications
Notifications to inform the user of specific situations related to the context, such as when confirming or obtaining data from the user.
Loading
Modals also display the stage of a process upon confirmation or continuation in transactional processes (e.g., exporting, importing, sending e-invoices). When using this component, the modal's width should be fixed.
Accessibility
Keyboard navigation
- ESC (escape) for closing or dismissing the modal
- Tab key for navigation between interactive components.
- Space bar for selecting the selected element.
- Enter to validate the selected element.
Tab order
- Starting with the first interactive component in a modal
- Continue from left to right and top to bottom through the rest of the body elements.
- Primary action
- Secondary action