An interface element that is displayed over a page. It can house any kind of content and requires the user to interact with it.



Storybook failed to load. Please connect to the VPN to access.


                                                            headline="Modal Headline"
                                                            <usln-button slot="trigger" label-text="Trigger Button" type="primary">
                                                                Open Modal
                                                            <div slot="modal-content">
                                                               Example text. You can display any type of content inside a modal.

Light modal example with headline icon, default button set and slots for trigger and content


Use this component for:

  • Eliciting user action (with transactional or destructive modals)
  • Displaying forms
  • Displaying information
  • Alerts (replace browser alerts where possible)





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.



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.



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 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.



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 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".



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.
Storybook failed to load. Please connect to the VPN to access.


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).

Storybook failed to load. Please connect to the VPN to access.


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.

Storybook failed to load. Please connect to the VPN to access.


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.
custom modal




600px width. Use to display rich or complex content, such as forms, illustrative modals. Mostly used in Portal.


480px width. Used to display simple content, such as warnings, browser confirmation. Mostly used in Editor.


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.