--- title: "Modal" navTitle: "Modal" summaryParagraph: A modal shows additional content in a layer above the page with a backdrop overlay covering the page behind. Use sparingly. tags: ["Modal window", "Dialog", "Pop up", "Alert", "Lightbox", "Overlay"] needToKnow: - "Modals need a trigger to open like a button." - "Modals need an overlay behind them and over the page." - "Choose your type (confirmation, informative, etc.)." - "Use sparingly." demoStoryId: modal-react--confirmation-positive-kaizen-site-demo demoStoryHeight: 500px --- ## Visuals ## Options * Presets: * Confirmation: * Mood: * Destructive / Negative * Affirmative / Positive * Informative * Input/edit * Information ## To keep in mind Modals contain smaller pieces of additional content while maintaining the context of the rest of the page, covered by a transparent overlay. * Trigger: * To trigger a modal, use a button. Alternatively, trigger on page load but this risks people dismissing without reading. ### All modals * All modals are dismissible (Close button, cancel button, Esc keystroke, Click outside). * Always a single primary action. Never two action buttons. If a second action is an option, use a control link (e.g. Cancel (Cluny, no underline). Always align button to the center of modal. * Where appropriate, use precise language and match the heading and primary button e.g. heading is “Delete photo” and primary button is “Delete”. Avoid questions like “Are you sure?”. * Close icon sits top right, never outside of modal. Screen reader reads icon name, i.e. “Close”. * The overlay is pure black (not Ink) with 50% opacity. * Directional modal carousel? Modals shouldn’t be used as carousels. Progress stepper in modal is preferable if you need to guide a user through a flow. * Never stacks multiple modals together on screen at the same time. ### Confirmation modal The confirmation modal confirms the end result of an action such as Negative or Positive actions. - Small: 300px wide x Height (Header, footer, margins and 1 line of content). Primarily for mobile use. - Medium: 600px wide x 600px H. - Large: 800px wide x 800px H - Header: States what the intent of Modal is. A verb and a noun (e.g. Upload an image, Notify users, Restart imports etc.) - Footer: Primary/Destructive action label reflect the action they are performing (relative to the header). ### Input/edit modal Input/edit modals allow people to change data or settings without leaving the page. They support the ability to edit up to 3 fields. Any more becomes crowded and a new page or Isolation modal is preferred. An input/edit modal may also be used to present data-intensive information such as a list of employees where the information modal is inappropriate. If data will be lost by dismissing the modal unintentionally, consider autosaving. - Min: 300px wide x Height (Header, footer, margins and 1 line of content). - Max: 800px x 600px (Must fit in laptop/mobile screen) - Header: Should state what the intent of Modal is. A verb and a noun (e.g. Upload an image, Notify users, Restart imports etc.) - Footer: Primary/Destructive action label should reflect the action they are performing (relative to the header). - Body: Adding a stone colored background will assist the definition of Inputs and will allow product team to clearly identify the modal type. ### Information modals Information modals assist with education. They’re user triggered. They may be relative to a deeper level of information. May be useful for first time users. Heavily optional. Visual aid is good. Primary action optional. - Header: State what the intent of Modal is. A verb and a noun (e.g. Upload an image, Notify users, Restart imports etc.). - Footer: Does not require a Primary/Destructive action. Avoid using unnecessary acknowledgment buttons, e.g. ‘Okay, got it!’. - Visuals: use illustrations instead of screenshots where possible. - Illustrations may last longer without needing to be updated as well as potentially have a smaller file size than a screenshot. - If you need a new illustration, see [illustrations](/guidelines/illustrations). ## When to use - Use a modal when you need to **change the flow of content or interaction** and yet maintain the context of the existing page or task. - Modals can be **disruptive and intrusive so use sparingly**. To avoid “banner blindness” and to avoid people immediately dismissing modals without reading them, show only on user interactions like a clicked button, not system driven events such as immediately on page load. - **Don’t trigger modals automatically without user interaction** at any time other than page load. That is, don’t trigger modals on scroll or after some time viewing a page. This risks inaccessibly stealing keyboard focus, disorienting the user, and introducing mode errors. ## When not to use - Avoid using modals on **small screens**. - Avoid using modals when the additional content is a huge **change in context**. Consider linking to a separate page. - Avoid using modals containing **image content** that is difficult to zoom on touch devices. - Avoid using modals when you can immediately **present actions inline** without cluttering the UI. For example, you might show a dropdown instead of a modal containing radio buttons. - Avoid using modals when you can **display content inline**. Consider using a collapsible “disclosure” element. - Avoid using modals when people **need to see the rest of the screen**. Consider using a [Popover](/components/popover) or [Tooltip](/components/tooltip) instead. - Instead of an informative modal, you might use an [inline notification](/components/inline-notification). - Instead of a modal, consider [Overview: tooltips, popovers, modals](/guidelines/overview-tooltips-popovers-modals). - Instead of a modal, consider a separate page. - Instead of a modal, consider collapsible “disclosure” elements. - Instead of a modal, consider inline actions. ## External Links Here are some examples of other existing design systems: - [Polaris: modal](https://polaris.shopify.com/components/overlays/modal). - [Lightning design: Modal](https://www.lightningdesignsystem.com/components/modals/#site-main-content). - [Atlassian: modal dialog](https://www.atlassian.design/guidelines/product/components/modal-dialog). - [Atlassian: inline dialog](https://www.atlassian.design/guidelines/product/components/inline-dialog). - [Material design: dialogs](https://material.io/design/components/dialogs.html). - [W3C: ARIA practices for dialog modal](http://w3c.github.io/aria-practices/#dialog_modal). - [Ant Design: feedback](https://ant.design/docs/spec/feedback).