docs/extension-test-page
What's New

Modal

Figma Storybook GitHub

A modal focuses the user's attention on a single task or message.

Preview

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.

Do

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

Don’t

  • 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 critical, positive, 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).

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.
Item
Applies to
Description

Variants and Examples

Base Style

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.

Critical

A modal style for destructive or irreversible actions.

Full Screen

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

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.

Has Banner

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

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.

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.

Vue API 

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

Slots

Name
Type
banner

Slot for the banner, defaults to bannerHeaderText prop

default

Default slot for dialog body section, taking the place of any "copy" text prop

footer

Slot for dialog footer content, often containing cancel and confirm buttons.

header

Slot for dialog header section, taking the place of any "headerText" text prop

Props

Name
Default
Type
appendTo
string

A CSS selector string for the element to portal the modal to. If not provided, the modal will be rendered in its default location.

bannerClass
''
string|object|array

Additional class name for the banner element within the modal. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

bannerHeaderText
string

Header text to display in the modal banner.

bannerKind
'warning'
"base" | "critical" | "info" | "positive" | "warning"

Sets the color of the banner.

closeOnClick
true
"true" | "false"

Whether the modal will close when you click outside of the dialog on the overlay.

contentClass
''
string|object|array

Additional class name for the content element within the modal. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

contentMode
"light" | "dark" | "invert"

Applies a color mode to the positioned content element. light and dark are explicit overrides. invert computes the opposite of the nearest ancestor's mode and stays reactive.

copy
''
string

Body text to display as the modal's main content.

describedById
''
string

Id to use for the dialog's aria-describedby. Recommended only if the dialog content itself isn't enough to give full context, as screen readers should recite the dialog contents by default before any aria-description.

dialogClass
''
string|object|array

Additional class name for the dialog element within the modal. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

fixedHeaderFooter
true
"true" | "false"

Scrollable modal that allows scroll the modal content keeping the header and footer fixed

footerClass
''
string|object|array

Additional class name for the footer element within the modal. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

headerClass
''
string|object|array

Additional class name for the header element within the modal. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

headerText
string

Header text to display in the modal header.

initialFocusElement
'first'
string|HTML_ELEMENT_TYPE

The element that is focused when the modal is opened. This can be an HTMLElement within the modal, a string starting with '#' which will find the element by ID. 'first' which will automatically focus the first element, or 'dialog' which will focus the dialog window itself. If the dialog is modal this prop cannot be 'none'.

kind
'default'
"default" | "critical"

The theme of the modal.

labelledById
generated unique ID
string

Id to use for the dialog's aria-labelledby.

modalClass
''
string|object|array

Additional class name for the root modal element. Can accept String, Object, and Array, i.e. has the same API as Vue's built-in handling of the class attribute.

open
false
"true" | "false"

Whether the modal should be shown. Parent component can sync on this value to control the modal's visibility.

showClose
true
"true" | "false"

Shows the close button on the modal

size
'default'
"default" | "full"

The size of the modal. size - default or full,

transparentBackdrop
false
"true" | "false"

When true, the surrounding backdrop is rendered fully transparent instead of the default dimming overlay. The dialog box itself remains opaque. Useful when the underlying UI should remain visible.

Events

Name
Type
click
PointerEvent | KeyboardEvent

Native button click event

keydown
KeyboardEvent

Native keydown event

update:open
Boolean

The modal will emit a "false" boolean value for this event when the user performs a modal-closing action. Parent components can sync on this value to create a 2-way binding to control modal visibility.

Classes

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

Class
Applies to
Description

Modal documentation last updated Thursday, June 18, 2026