Preview
Code
<usln-modal
size="large"
theme="light"
is-open="true"
headline="Modal Headline"
primary-button-text="Save"
header-icon="folder"
button-set="default"
secondary-button-text="Cancel"
>
<usln-button slot="trigger" label-text="Trigger Button" type="primary">
Open Modal
</usln-button>
<div slot="modal-content">
Example text. You can display any type of content inside a modal.
</div>
</usln-modal>
Guidelines
Use this component for:
- Eliciting user action (with transactional or destructive modals)
- Displaying forms
- Displaying information
- Alerts (replace browser alerts where possible)
Behaviour
Trigger
The modal is triggered with a button element or displayed automatically in response to a user action (e.g. warning about impact of this user action). The system does not display modals on its own.
Display
The modal is displayed on an overlay of RGBA (9, 4, 32 .4). The default modal position is horizontally centred, with 94px vertical offset from the top of the viewport.
Closing
The modal can be closed with the X icon button or the secondary button in the modal. It does not close when users click outside of it to prevent accidental closing.
Scrolling
Scrolling can happen inside the modal (though ideally content should fit without the need to scroll) OR inside the viewport, outside the modal. Modals prevent the underlying page from being scrolled.
Do's and dont's
- DO try to avoid scrolling the content within the modal - consider a separate page if you cannot prevent content scrolling at a reasonable screen size.
- DON'T use modals for complex, multi-step interactions where the entire content of the modal would have to be changed. In this case users would be better served by a dedicated flow or page.
- DON'T use modals when having a shareable URL would be beneficial (opt for a page instead).
Content guidelines
Use consistent vocabulary between modal headline, body content, and buttons.
Headline
Modal headlines should concisely describe the purpose of the modal or required action. Avoid titles that break into multiple lines.
Body content
Modals can carry all kinds of content inside them, so follow content guidelines for the respective elements. Keep text content clear and reasonably short.
Button
Button labels should be short and describe an action or result. Single verb labels are ideal. Avoid long labels with superfluous action description, e.g. "Cancel and Return".
Variants
Transactional (default) modal
Use to validate user decisions or focus their attention on a specific action.
Button sets:
- When using two buttons, the rightmost button is always the primary user action, while the secondary button allows user to close the modal without performing the action or accepting changes.
- Three buttons: use if you need a secondary destructive action in addition to the two buttons, but this action is not the main purpose of the modal.
Destructive modal
Use to ellicit user confirmation on destructive actions, such as deleting entities or discarding changes. It's not necessary to display it when the action is recoverable (e.g. deleted guides can be recovered from trash).
Illustrative modal
Use to display information and offer follow-up steps or alternatives, particularly when you want to soften the message or humanize the context for the user.
Custom modal
Use this variant to display entirely custom content. This is an empty modal container that will come without predefined content, buttons, or size. Remember to still follow the relevant design guidelines for its content, and to include the following elements:
- a headline describing the purpose of the modal or the required action
- a way to close the modal
- any buttons necesary for users to perform the action.
Size
L
600px width. Use to display rich or complex content, such as forms, illustrative modals. Mostly used in Portal.
M
480px width. Used to display simple content, such as warnings, browser confirmation. Mostly used in Editor.
Custom
If you're using a custom modal, you can use either of the above sizes, or define a specific modal width that fits your content. Please use the grid system as guidelines.
Tracked events
Modal usage is tracked under following events:
- modalEvent category, where event labels: [primary button event], [secondary button event], [tertiary button event] are specified per instance.
- iconbuttonClose label is used for closing the modal.
Any interaction with modal content has to have event tracking specified separately.