Dialog

Live

Open one and press Escape, then Tab around. The focus trap, the inert background and the backdrop are the platform's, not ours.

Code

<GdDialog v-model:open="open" title="Email this report?" confirm-label="Send" @confirm="send">
  A PDF of 42 Jarrah Street goes to [email protected].
</GdDialog>

<GdDialog
  v-model:open="removing"
  title="Remove this parcel from the project?"
  confirm-label="Remove parcel"
  confirm-word="Jarrah"
  danger
  @confirm="remove"
>
  42 Jarrah Street and its saved scenarios will be deleted. Reports you have
  already emailed stay valid.
</GdDialog>

API

Props

PropTypeDefault

openrequiredboolean—

Whether it is showing, as `v-model:open`. The platform can close the dialog without us — Escape, the backdrop — and the component writes `false` back when it does.

titlerequiredstring—

The heading, and the dialog's accessible name via `aria-labelledby`.

confirmLabelstring"Confirm"

The label on the confirming action. Say what it does — "Send", "Remove parcel" — not "OK".

confirmWordstring—

Typed confirmation, for anything irreversible. The primary action stays inert until the user types this word; the field is cleared each time the dialog opens.

dangerboolean—

Draws the confirming action as the danger button. Never use it without `confirmWord`.

busyboolean—

Puts the confirming action in its loading state while the work runs.

Slots

default

The consequence, in a sentence or two. Say what will be destroyed and what survives.

Events

confirm

The confirming action was pressed. It does not close the dialog — the caller closes it when the work is done.

cancel

The PLATFORM closed it — Escape — and the component wrote `open` back to false so the two cannot desync. The Cancel button sets `open` to false directly and does not emit this.

Usage Guidelines

Do

Use a dialog when requesting confirmation for destructive actions (delete, discard, overwrite).
Pair danger with confirmWord to ensure explicit secondary confirmation.
Explain the consequence clearly in the dialog body, including what survives the action.
Handle closing manually after @confirm completes, utilizing the busy state during asynchronous work.

Don't

Don't use a dialog for non-blocking explanations or definitions. Use a Popover instead.
Don't use a dialog for complex, multi-step workflows. Use a Drawer instead.
Don't rely on a red button alone as a safeguard for destructive actions.

Behavior & Anatomy

Implementation Details

The component is built using the native <dialog> element and showModal() API. This provides a built-in focus trap, top-layer stacking, and native Escape key dismissal.