Overlay Usage

Imagine you have a page, and you want to allow the user to complete a task, or perhaps a complex series of tasks, without feeling lost or having to leave to another page. If that’s the case, an overlay might be the right fit. In this guide, we'll outline several different kinds of overlays, and explain when to use them.


Modals are the default overlay solution and will work for most use cases. If you have a simple confirmation message or form, consider using a modal.
Don’t use modals with a panel, or any complex content, inside. If the experience starts to become complicated, consider a tearsheet instead.
Don’t use modals for dense or large content, like tables or big multi-column forms.

Modal Wizards

The stepper component does not exist yet in Core React. Please help contribute it!

Some tasks may lend themselves to being broken into steps, especially linear forms that require one section to be completed before another. In these cases you may find a modal wizard (a modal with a stepper inside) to be a good fit. Using a wizard, you can progressively disclose content to avoid overwhelming the user.


Tearsheets are optimal when you want to take a user through a complex experience while maintaining the context of the current page.

Tearsheets excel at embedding a large variety of content - because there’s no inherent header or footer inside a tearsheet, you can embed entire pages without needing to redesign them.

When considering a tearsheet, weigh it against the pros and cons of just taking the user to a new page. For example, it might be better to navigate to a new page if the user will continue on without returning to the parent page. If the user will be in the tearsheet for a long time, it might be better to use a new page as well. But if the task requires opening the tearsheet, making some changes, and closing, it’s a great solution.

Tearsheets can also be overkill for simple tasks. Ask yourself how complex or simple the action is, and if a tearsheet is warranted versus a modal.
Don’t use tearsheets without a scrim. Tearsheets are not ideal for comparing information side by side - in these cases we recommend using a panel.


This component does not exist yet in Core React! If you are able to contribute it, please reach out to us.

A “lightbox” is similar to modal, but offers features tailored to viewing images, documents, and other media. It might allow the user to pan and zoom, switch pages in a PDF, download the original file, or mark up and annotate documents.

If a user needs to preview something, like an image or document, a lightbox is ideal.

Stacking Overlays

You can trigger multiple overlays one after the other as needed. However,  be mindful of the sense of space this creates. If a modal launches a tearsheet that launches another modal, etc. then perhaps the user should be taken to a different page. As a general rule, two overlay elements (a tearsheet and a modal, or a modal on top of a modal) are relatively safe to use.

Appropriate times to nest overlays are for alerts and lightweight dialogs, and ensuring the overlapping modal is small will help the user see behind it and not lose their sense of space. One common example is to ask the user if they want to discard their changes.If you suspect your users will get lost (or even better, if you observe this when testing) consider taking the user to a new page instead somewhere earlier on in the experience.


Overlay elements like modals and tearsheets are designed to be focused, singular experiences, and their scrims obscure the page underneath. For that reason, they aren’t the best fit for comparing and contrasting information side by side.

If you’re trying to compare two or more items, and especially if your user needs to multitask, start by considering a panel. If the panel is not the right fit, reach out to us to talk about possible contributions or directions you can take.

In Closing

These guidelines are only intended as tools to help you answer your own UX questions. Design decisions are complex and other factors might overrule these. One example is consistency; if you are already using one type of pattern everywhere else, it might make sense to follow that pattern even if it's not intuitive by itself. If you’re still unsure about which pattern to use, reach out and we’ll be happy to help go over some options with you.