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

Create a controller and render <OverlayHost :host="overlays" /> before calling the function returned by useOverlays() or createOverlayService(host). 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 { useOverlays } from '@chillet/m3-vue';

const { showDialog } = useOverlays(); // Capture during setup.
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.
• Unmounting or disposing the target host rejects pending calls.
• 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.
• The promise resolves when the native dialog closes. Cleanup still waits for all Dialog-owned exit motion, including the backdrop, before removing the dialog from the host, so cleanup does not delay the existing result timing.

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