Modal

Usage #

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. By design, clicking outside the DtModal dialog does not close it — this is intentional behavior to prevent accidental dismissal of important tasks. Users must explicitly click the close button or trigger a close action to dismiss 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.

Best Practices #

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

Accessibility #

• 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 a tags must have an hrefattribute. Also, any elements which you don't want to be focusable (but might be focusable by default) must have their tabindex set 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-labelledby on its root element to associate a title to the modal to announce its to accessible technology. The value of aria-labelledby is to the id value of its heading element (e.g. h2).
• Dismissing Modal returns focus to the originating element that spawned the modal's display.

Variants and Examples #

Base Style #

<dt-modal
  header-text="Example title"
  :open="isOpen"
  @update:open="updateOpen"
  copy="Lorem ipsum ..."
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Fixed Header and Footer #

This is the default behavior that adds the scroll automatically in the modal content and leaves the header and footer fixed.

<dt-modal
  header-text="Example title"
  :open="isOpen"
  @update:open="updateOpen"
  :showFooter="true"
  :fixed-header-footer="true"
  copy="Sed at orci quis nunc finibus gravida eget vitae est..."
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Critical #

A modal style for destructive or irreversible actions.

<dt-modal
  header-text="Example title"
  :open="isOpen"
  kind="critical"
  copy="Sed at orci quis nunc finibus gravida eget vitae est..."
  @update:open="updateOpen"
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      kind="critical"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Full Screen #

To make this modal take up as much of the screen as possible.

<dt-modal
  header-text="Example title"
  :open="isOpen"
  fullscreen
  copy="Sed at orci quis nunc finibus gravida eget vitae est..."
  @update:open="updateOpen"
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Transparent Backdrop #

By default, modals render a dimming overlay behind the dialog box. Set transparent-backdrop to render the surrounding backdrop fully transparent. The dialog box itself keeps its solid background. Use this when the underlying UI should remain visible behind the modal.

<dt-modal
  header-text="Example title"
  :open="isOpen"
  transparent-backdrop
  copy="Sed at orci quis nunc finibus gravida eget vitae est..."
  @update:open="updateOpen"
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Has Banner #

When there is a need of more context information regarding the content of the Modal

<dt-modal
  header-text="Example title"
  :open="isOpen"
  banner-header-text="This banner can have different kinds."
  :bannerKind="selectedBannerKind"
  copy="Sed at orci quis nunc finibus gravida eget vitae est..."
  @update:open="updateOpen"
>
  <template
    #footer
  >
    <dt-button
      id="cancel-button"
      :kind="secondaryButtonKind"
      importance="clear"
    >
      Cancel
    </dt-button>
    <dt-button
      id="confirm-button"
      importance="primary"
    >
      Confirm
    </dt-button>
  </template>
</dt-modal>
<dt-button
  @click="isOpen = !isOpen"
>
  Click to open
</dt-button>

Custom Header and Content #

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.

<dt-modal
  :open="isOpen"
  @update:open="updateOpen"
>
  <template #header>
    <dt-stack direction="row" align="center" justify="center" class="d-p-150 d-bgc-purple-100">
      <div>Custom header</div>
    </dt-stack>
  </template>
  <dt-stack direction="row" align="center" justify="center" class="d-p-400 d-bgc-gold-200">
    <h2>Custom content</h2>
  </dt-stack>
</dt-modal>

Content Mode #

Modal content renders outside the DOM tree. Use the contentMode prop to apply color mode (invert, light, dark) to the positioned content. See Positioned Components for details.

<dt-modal content-mode="invert">...</dt-modal>
<dt-modal content-mode="dark">...</dt-modal>
<dt-modal content-mode="light">...</dt-modal>

Vue API #

import { DtModal } from '@dialpad/dialtone-vue';

Slots

Props

Events

Classes #

At minimum, modals contain a title and one button. They could also contain body text, brand illustrations, product wireframes, or multiple buttons.