Vastu

Dialog <va-dialog>

Asks the user to confirm, decide or enter something before going back to the page.

When to use it

Use it
For a decision the user must make before going on, such as confirming a deletion, or a short focused task.
Don't use it
For information that doesn't need a response, or for long, multi-step flows.
Use instead
va-toast for confirmations that need no response; a full page for long flows.

Examples

Confirm a destructive action

A va-button with commandfor and command="--show" opens the dialog without any script. Focus returns to it on close.

Delete project

“Atlas” and its 14 files will be deleted for everyone. You can't undo this.

Cancel Delete project
<va-button variant="danger" commandfor="delete-dialog" command="--show">Delete project</va-button>
<va-dialog id="delete-dialog" heading="Delete this project?">
  <p>“Atlas” and its 14 files will be deleted for everyone. You can't undo this.</p>
  <va-button slot="footer" variant="secondary" commandfor="delete-dialog" command="--close">Cancel</va-button>
  <va-button slot="footer" variant="danger">Delete project</va-button>
</va-dialog>

A short form

Focus starts on the first field. Escape or the close button cancels.

Rename Cancel Save
<va-button commandfor="rename-dialog" command="--show">Rename</va-button>
<va-dialog id="rename-dialog" heading="Rename file">
  <va-text-field label="File name" value="notes-final-v2.md"></va-text-field>
  <va-button slot="footer" variant="secondary" commandfor="rename-dialog" command="--close">Cancel</va-button>
  <va-button slot="footer">Save</va-button>
</va-dialog>

Install and import

npm install @firstprateek/vastu @firstprateek/vastu-tokens
import '@firstprateek/vastu-tokens/lekha.css'; // once per page
import '@firstprateek/vastu/dialog';

API

Attributes and properties

AttributePropertyTypeDefaultDescription
openopenbooleanfalseWhether the dialog is open. Prefer show() and close(), or command="--show" on a va-button.
headingheadingstring''The visible heading. It is also the dialog's accessible name.
labellabelstring''Accessible name, when there is no visible heading.
hide-close-buttonhideCloseButtonbooleanfalseHides the close button in the header, for a dialog that needs an explicit choice. Escape still closes it.

Events

EventDescription
va-openAfter the dialog opens.
va-closeBefore the dialog closes. Cancel it with preventDefault() to keep the dialog open. event.detail.reason is escape, close-button, command or method.

Slots

SlotDescription
(default)The dialog's content.
footerActions, such as Cancel and Confirm buttons. Put the primary action last.

Methods

MethodDescription
show()Opens the dialog as a modal.
close()Closes the dialog, unless a va-close listener cancels it.

Styling

Components read the brand's tokens. To adjust one component, set its custom properties or style its parts.

Custom propertyTypeDescription
--va-dialog-bg<color>Background colour.
--va-dialog-width<length>Maximum width.
--va-dialog-radius<length>Corner radius.
PartDescription
::part(dialog)The native dialog element.
::part(header)The row with the heading and the close button.
::part(heading)The heading.
::part(close)The close button.
::part(body)The wrapper around the content.
::part(footer)The wrapper around the actions.

Accessibility

Role
dialog
Accessible name
The heading, or label when there is no visible heading.
Note
The page behind is inert while the dialog is open, so focus and screen readers stay inside it.
Note
On open, focus goes to the first element with autofocus, else the first focusable control in the content, else the close button.

Keyboard

KeyDoes
EscapeCloses the dialog and returns focus to the element that opened it.

Every row on this page is checked by contract tests generated from the same manifest, in Chromium, Firefox and WebKit. Read the manifest.