showDialog

showDialog() is the programmatic entry point for modal dialogs. It renders a Dialog through the application's OverlayHost, waits for it to close, and resolves with the dialog result.

Prerequisite

Render one OverlayHost near the application root before using this function. The host is only required for programmatic overlays; declarative Dialog instances do not need it. See OverlayHost for Vue and Nuxt setup.

Basic Usage

import { showDialog } from '@chillet/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. All actions render as text buttons, including primary and destructive actions. Their hierarchy comes from labels, order, and position rather than a filled, tonal, or outlined variant.

Options

The tables below are generated from source types and stay in sync with API changes.

ShowDialogOptions

Field	Type	Required	Description	Default
headline	string	No	Optional dialog headline text.	-
content	string	No	Optional supporting text content.	-
icon	string	No	Optional Material Symbols icon name rendered above the headline.	-
actions	DialogAction[]	No	Action buttons rendered in the dialog footer.	-
closeOnBackdrop	boolean | undefined	No	Whether clicking the backdrop closes the dialog.	true
role	'dialog' | 'alertdialog'	No	ARIA role forwarded to the root dialog element.	-

DialogAction

Field	Type	Required	Description	Default
label	string	Yes	Label shown in the action row.	-
value	string | undefined	No	Value returned when this action closes the dialog.	-
disabled	boolean | undefined	No	Whether the action button is disabled.	-
autofocus	boolean | undefined	No	Whether this action should autofocus when rendered.	-
closeOnClick	boolean | undefined	No	Whether clicking the action should close the dialog.	-
onClick	(() => void | boolean | Promise<void | boolean>) | undefined	No	Optional callback invoked before the dialog closes. Return `false` to keep it open.	-

Behavior Notes

• Calling showDialog() outside a browser environment rejects the promise.
• Calling showDialog() without a mounted OverlayHost rejects the promise.
• The dialog inherits application-level provides and CSS custom properties from the host.
• If an action callback throws or rejects, the promise rejects with that error.
• Cleanup waits for the dialog exit animation before removing it from the host.

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