showDialog

showDialog() is the programmatic entry point for modal dialogs. It mounts a temporary Dialog instance, waits for it to close, and resolves with the dialog result.

Basic Usage

import { showDialog } from '@rikkaw/m3-vue';

const result = await showDialog({
  headline: 'Delete file?',
  content: 'This action cannot be undone.',
  actions: [
    { label: 'Cancel', value: 'cancel' },
    { label: 'Delete', value: 'confirm' },
  ],
});

The promise resolves to the clicked action value. If no explicit value is provided, the action label is used instead.

Options

Field	Type	Default	Notes
headline	string	-	Optional dialog title
content	string	-	Optional supporting text
icon	string	-	Material Symbols icon name rendered in the icon slot
actions	DialogAction[]	[{ label: 'OK', value: 'confirm', color: 'text' }]	Footer actions
closeOnBackdrop	boolean	true	Closes when the backdrop is clicked
role	'dialog' | 'alertdialog'	-	Forwarded to the rendered <dialog> element

DialogAction fields:

Field	Type	Default	Notes
label	string	-	Visible button text
value	string	label	Value used to resolve the promise
color	ButtonProps['color']	'text'	Button style
disabled	boolean	false	Disables the action
autofocus	boolean	false	Autofocuses the action button
closeOnClick	boolean	true	Keep the dialog open by setting this to false
onClick	() => void | boolean | Promise<void | boolean>	-	Return false to keep the dialog open

Behavior Notes

• Calling showDialog() outside a browser environment rejects the promise.
• If an action callback throws or rejects, the promise rejects with that error.
• Cleanup waits for the dialog exit animation before unmounting the temporary app host.

For manually rendered dialogs and slot-based composition, see Dialog.