Modal

Storybook Figma

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

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 href attribute. 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 it to assistive technology. The value of aria-labelledby should match the id of its heading element (e.g. h2).
  • Dismissing the 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.

Danger

A modal style for destructive or irreversible actions.

Full Screen

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

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.

Vue API

Slots

Name
Description
banner

Slot for the banner, defaults to bannerTitle 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 "title" text prop

Props

Name
Description
Default
appendTo

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

 Type: string
undefined
bannerClass

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.

 Type: string|object|array
''
bannerKind

Sets the color of the banner.

 Type: string
Values: baseerrorinfosuccesswarning
 'warning'
bannerTitle

Title text to display in the modal banner.

 Type: string
''
closeOnClick

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

 Type: boolean
Values: truefalse
 true
contentClass

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.

 Type: string|object|array
''
copy

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

 Type: string
''
describedById

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.

 Type: string
''
dialogClass

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.

 Type: string|object|array
''
fixedHeaderFooter

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

 Type: boolean
Values: truefalse
 true
hideClose

Hides the close button on the modal

 Type: boolean
Values: truefalse
 false
initialFocusElement

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

 Type: string|HTML_ELEMENT_TYPE
'first'
kind

The theme of the modal. kind - default or danger,

 Type: string
Values: defaultdanger
 'default'
labelledById

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

 Type: string
function () { return getUniqueString(); }
modalClass

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.

 Type: string|object|array
''
show

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

 Type: boolean
Values: truefalse
 false
size

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

 Type: string
Values: defaultfull
 'default'
title

Title text to display in the modal header.

 Type: string
''

Events

Name
Description
click

Native button click event

 Type: PointerEvent | KeyboardEvent
keydown

Native keydown event

 Type: KeyboardEvent
update:show

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.

 Type: Boolean

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 11, 2026