| title | description | status | thumb | image | storybook | figma_url | keywords | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Modal |
A modal focuses the user’s attention on a single task or message. |
ready |
true |
assets/images/components/modal.png |
|
Modals disable underlying content and are used to present a short-term task the user needs to perform without losing the context of the underlying page. Users won't be able to interact with the page until they close the modal.
Although highly versatile, this doesn't mean modal dialogs are fit for all purposes. Modals are purposefully disruptive and should be used thoughtfully and sparingly, specifically in moments where focus is required or an action must be taken.
- To complete a simple task or decision that requires their full attention outside the main workflow.
- Confirming a destructive action that is about to happen.
- Ask for a user’s consent for an action.
<template #dont>
- When its content or features can be part of the page without complicating the page’s intent.
- When the content or message requires interaction with other parts of the application or screen.
- Form-related error, success, or warning messages. Keep feedback in context to forms.
- Confirming an action took place (instead: use a Toast).
- Revealing more information (instead: place content inline)
- Displaying complex forms or large amounts of information (instead: place content inline)
- Displaying content unrelated to current task (instead: place content inline as a Link or Banner).
- Ideally, users trigger the modal, not the system, and should not be a surprise. Its appearance should reflect user intent to invoke it. Uninvited modals may surprise the user and result in a quick dismissal of the window.
- Treat modals as a last resort. Consider whether there’s another component or UI that might be less disruptive for the user.
- Limit the number of interactions in a modal. Remove anything that does not support the task.
- Avoid multiple steps that require navigation within the modal dialog.
- Avoid complex decision-making that requires additional sources of information unavailable in the modal.
- Use clear header and action labels. Label links and buttons with a verb that avoids ambiguity and clearly indicates what happens when it’s selected. The primary action’s label should complement the modal title.
- Avoid lengthy contents that require scrolling.
- Only one modal can be present at a time.
- Opened modals “trap focus,” meaning keyboard navigation controls are constrained to elements within the modal. Tabbing to the modal's last focusable element, and then pressing tab again would loop the focus back to the first element on the page. Focus doesn't return to the underlying page until the user explicitly dismisses the modal, in which case it would return to the place it was before the dialog opened.
- To ensure maximum compatibility, all
atags must have anhrefattribute. Also, any elements which you don't want to be focusable (but might be focusable by default) must have theirtabindexset to-1. - Focus should always begin on the first actionable element within the dialog. This could be an OK button, or the first field in the form. An X button in the top right corner should be last in the tab order even though it may be visually above the other elements.
- Check out the "Focus management" section of the following MDN Dialog document if you'd like to know more.
- Use
aria-labelledbyon its root element to associate a title to the modal to announce its to accessible technology. The value of aria-labelledby is to theidvalue of its heading element (e.g.h2). - Dismissing Modal returns focus to the originating element that spawned the modal’s display.
<code-example-tabs htmlCode=' Click to open
Sed at orci quis nunc finibus gravida eget vitae est...
This is the default behavior that adds the scroll automatically in the modal content and leaves the header and footer fixed.
<code-example-tabs htmlCode=' Click to open
Sed at orci quis nunc finibus gravida eget vitae est...
A modal style for destructive or irreversible actions.
<code-example-tabs htmlCode=' Click to open
Sed at orci quis nunc finibus gravida eget vitae est...
To make this modal take up as much of the screen as possible.
<code-example-tabs htmlCode=' Click to open
Sed at orci quis nunc finibus gravida eget vitae est...
When there is a need of more context information regarding the content of the Modal
<code-example-tabs htmlCode=' Click to open
You're not limited to using plain title and copy text.
In addition to the footer, custom elements can be inserted into the header and body sections of the dialog via slots.
Please note: supplied header or body slots will take the place of any provided "title" or "copy" text, respectively.
<code-example-tabs vueCode=' <dt-modal :show="isOpen" @update:show="updateShow"
<template #header>
At minimum, modals contain a title and one button. They could also contain body text, brand illustrations, product wireframes, or multiple buttons.
<script setup> import ExampleModal from '@exampleComponents/ExampleModal.vue'; import { ref } from 'vue'; const isOpen = ref(false); const selectedBannerKind = ref('success'); const fixedHeaderFooterCopy = ref(`Sed at orci quis nunc finibus gravida eget vitae est. Praesent ac laoreet mi. Cras porttitor mauris ex. Integer convallis tellus a ex egestas, id laoreet elit mollis. Mauris ut elementum velit. Nam vel consectetur turpis. Aenean consequat purus non nunc tincidunt rutrum. In semper pretium dui vel tempus. Proin et mi id mi egestas iaculis. Sed lacinia libero non molestie consequat. Sed efficitur purus eget lacus viverra volutpat. Nam luctus ac eros eu iaculis. Fusce non condimentum lorem.`.repeat(10)) const openModal = () => { isOpen.value = true; }; const updateShow = (value) => { if (!value) isOpen.value = false; }; const changeBannerKind = (kind) => { selectedBannerKind.value = kind; }; const bannerKinds = () => { return Object.keys(window.DIALTONE_CONSTANTS.MODAL_BANNER_KINDS); }; </script>