Skip to main content
Version: 1.x

fast-dialog

As defined by the W3C:

A dialog is a window overlaid on either the primary window or another dialog window. Windows under a modal dialog are inert. That is, users cannot interact with content outside an active dialog window. Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, and in some implementations, attempts to interact with the inert content cause the dialog to close.

Like non-modal dialogs, modal dialogs contain their tab sequence. That is, Tab and Shift + Tab do not move focus outside the dialog. However, unlike most non-modal dialogs, modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog.

Setup

import {
provideFASTDesignSystem,
fastDialog
} from "@microsoft/fast-components";

provideFASTDesignSystem()
.register(
fastDialog()
);

Usage

<fast-dialog id="example1" class="example-dialog" aria-label="Simple modal dialog" modal="true" hidden>
<h2>Dialog</h2>
<p>This is an example dialog.</p>
<fast-button>Close Dialog</fast-button>
</fast-dialog>

Create your own design

import { Dialog, dialogTemplate as template } from "@microsoft/fast-foundation";
import { dialogStyles as styles } from "./my-dialog.styles";

export const myDialog = Dialog.compose({
baseName: "dialog",
template,
styles,
});

API

class: Dialog

Superclass

NameModulePackage
FoundationElement/src/foundation-element/foundation-element.js

Fields

NamePrivacyTypeDefaultDescriptionInherited From
modalpublicbooleantrueIndicates the element is modal. When modal, user mouse interaction will be limited to the contents of the element by a modal overlay. Clicks on the overlay will cause the dialog to emit a "dismiss" event.
hiddenpublicbooleanfalseThe hidden state of the element.
trapFocuspublicbooleantrueIndicates that the dialog should trap focus.
ariaDescribedbypublicstringThe id of the element describing the dialog.
ariaLabelledbypublicstringThe id of the element labeling the dialog.
ariaLabelpublicstringThe label surfaced to assistive technologies.
$presentationpublicComponentPresentation or nullA property which resolves the ComponentPresentation instance for the current component.FoundationElement
templatepublicElementViewTemplate or void or nullSets the template of the element instance. When undefined, the element will attempt to resolve the template from the associated presentation or custom element definition.FoundationElement
stylespublicElementStyles or void or nullSets the default styles for the element instance. When undefined, the element will attempt to resolve default styles from the associated presentation or custom element definition.FoundationElement

Methods

NamePrivacyDescriptionParametersReturnInherited From
showpublicThe method to show the dialog.void
hidepublicThe method to hide the dialog.void
templateChangedprotectedvoidFoundationElement
stylesChangedprotectedvoidFoundationElement

Events

NameTypeDescriptionInherited From
cancelFires a custom 'cancel' event when the modal overlay is clicked
closeFires a custom 'close' event when the dialog is hidden

Attributes

NameFieldInherited From
modal
hidden
trap-focustrapFocus
aria-describedbyariaDescribedby
aria-labelledbyariaLabelledby
aria-labelariaLabel

CSS Parts

NameDescription
positioning-regionA wrapping element used to center the dialog and position the modal overlay
overlayThe modal dialog overlay
controlThe dialog element

Slots

NameDescription
The default slot for the dialog content

Additional resources