Dialog

Dialog provides a modal surface with headline, body, icon, and action slots built on the native <dialog> element.

Dialog actions use text buttons, including the primary, confirmation, final, and destructive actions. Express their hierarchy through clear labels, order, and position rather than filled, tonal, or outlined containers.

Delete file?

The file will be permanently removed from your workspace.

Close lifecycle

update:open(false) and close are emitted when the native dialog closes. Use them to update application state that controls whether the dialog is open. closed is emitted later, after the Dialog-owned visual exit—including its backdrop—has finished, with the same native dialog return value as close. It does not wait for animations inside slot content. With no motion or reduced motion, closed follows asynchronously without waiting for a timeout.

Keep slot data available during the exit and release it from closed:

<script setup lang="ts">
import { ref, shallowRef } from 'vue';

const open = ref(false);
const selectedItem = shallowRef<{ name: string } | null>(null);

function requestClose() {
  open.value = false;
}

function clearDialogContent() {
  selectedItem.value = null;
}
</script>

<template>
  <Dialog v-model:open="open" @closed="clearDialogContent">
    <template #headline>{{ selectedItem?.name }}</template>
    <Button variant="text" @click="requestClose">Close</Button>
  </Dialog>
</template>

Width

Use the width prop for the dialog surface width.

<Dialog width="28rem" />

For stylesheet-level customization, set --md-dialog-container-width on the Dialog root. The root native <dialog> remains fullscreen so backdrop clicks and modal positioning keep working, while the token controls the inner surface.

<Dialog class="wide-dialog" />

.wide-dialog {
  --md-dialog-container-width: 40rem;
}

Scrollable content

The content part preserves common descendant visual overflow at its block edges while remaining independently scrollable. See Scrollable Content Visual Overflow for the shared Dialog and sheet contract and its customization token.

Examples

Default

Delete file?

The file will be permanently removed from your workspace.

With Icon

info

Sync paused

Changes are saved locally and will upload automatically when the network is available again.

Floating surface

See floating surface tokens for shared theme colors, borders, shadows, and an interactive example with nested menus and dialogs.

Reference

Anatomy

Highlight

Element	Part	Selector
<dialog>	root	[data-scope="dialog"][data-part="root"] left_clickLMBCopy
<div>	surface	[data-scope="dialog"][data-part="surface"] left_clickLMBCopy
<div>	iconconditional	[data-scope="dialog"][data-part="icon"] left_clickLMBCopy
<h2>	headlineconditional	[data-scope="dialog"][data-part="headline"] left_clickLMBCopy
<div>	contentconditional	[data-scope="dialog"][data-part="content"] left_clickLMBCopy
<div>	actionsconditional	[data-scope="dialog"][data-part="actions"] left_clickLMBCopy

Props

Name	Description	Default	Control
shapeOptional	Corner style; inherits the shared shape default. M3Shape | undefined	-	-
closeOnBackdropOptional	Whether clicking the backdrop closes the dialog. boolean | undefined	true	check
widthOptional	Dialog surface width. Such as '28rem'. string | undefined	undefined
openOptional	- boolean | undefined	false

Events4

Name	Type	Description
close	[returnValue: string]	-
update:open	[value: boolean]	-
cancel	[event: Event]	-
closed	[returnValue: string]	-

Slots4

Name	Parameters	Description
icon	-	Optional leading icon content.
headline	-	Optional dialog headline.
default	-	Supporting text or custom body content.
actions	-	Action buttons row.

Styling26

Preview

Token	Description
--md-dialog-action-label-text-colorColor Fallbackvar(--md-sys-color-primary)	Controls action label text color.
--md-dialog-action-label-text-fontTypography Fallbackvar(--md-sys-typescale-label-large-font)	Controls action label text font.
--md-dialog-action-label-text-line-heightTypography Fallbackvar(--md-sys-typescale-label-large-line-height)	Controls action label text line height.
--md-dialog-action-label-text-sizeLayout Fallbackvar(--md-sys-typescale-label-large-size)	Controls action label text size.
--md-dialog-action-label-text-trackingTypography Fallbackvar(--md-sys-typescale-label-large-tracking)	Controls action label text tracking.
--md-dialog-action-label-text-typeTypography Fallbackvar(--md-sys-typescale-label-large)	Controls action label text type.
--md-dialog-action-label-text-weightTypography Fallbackvar(--md-sys-typescale-label-large-weight)	Controls action label text weight.
--md-dialog-container-colorColor Fallbackvar(--md-sys-color-surface-container-high)	Controls container color.
--md-dialog-container-elevationElevation Fallbackvar(--md-sys-elevation-level3)	Controls container elevation.
--md-dialog-container-shapeShape Fallbackvar(--md-shape-overlay)	Controls container shape.
--md-dialog-headline-colorColor Fallbackvar(--md-sys-color-on-surface)	Controls headline color.
--md-dialog-headline-fontTypography Fallbackvar(--md-sys-typescale-headline-small-font)	Controls headline font.
--md-dialog-headline-line-heightTypography Fallbackvar(--md-sys-typescale-headline-small-line-height)	Controls headline line height.
--md-dialog-headline-sizeLayout Fallbackvar(--md-sys-typescale-headline-small-size)	Controls headline size.
--md-dialog-headline-trackingTypography Fallbackvar(--md-sys-typescale-headline-small-tracking)	Controls headline tracking.
--md-dialog-headline-typeTypography Fallbackvar(--md-sys-typescale-headline-small)	Controls headline type.
--md-dialog-headline-weightTypography Fallbackvar(--md-sys-typescale-headline-small-weight)	Controls headline weight.
--md-dialog-supporting-text-colorColor Fallbackvar(--md-sys-color-on-surface-variant)	Controls supporting text color.
--md-dialog-supporting-text-fontTypography Fallbackvar(--md-sys-typescale-body-medium-font)	Controls supporting text font.
--md-dialog-supporting-text-line-heightTypography Fallbackvar(--md-sys-typescale-body-medium-line-height)	Controls supporting text line height.
--md-dialog-supporting-text-sizeLayout Fallbackvar(--md-sys-typescale-body-medium-size)	Controls supporting text size.
--md-dialog-supporting-text-trackingTypography Fallbackvar(--md-sys-typescale-body-medium-tracking)	Controls supporting text tracking.
--md-dialog-supporting-text-typeTypography Fallbackvar(--md-sys-typescale-body-medium)	Controls supporting text type.
--md-dialog-supporting-text-weightTypography Fallbackvar(--md-sys-typescale-body-medium-weight)	Controls supporting text weight.
--md-dialog-with-icon-icon-colorColor Fallbackvar(--md-sys-color-secondary)	Controls with icon icon color.
--md-dialog-with-icon-icon-sizeLayout Fallback1.5rem	Controls with icon icon size.