Dialog
A dialog is a temporary, modal overlay that can provide contextual information and/or require user confirmation or input.
Examples
Usage
Dialogs and corner dialogs consist of header, content, and footer areas (similar to panel ). When needed, custom dialogs can render custom layouts that don’t follow the structure of basic and corner dialogs.
Do
- Use dialogs to display transient information that needs user attention
- Use corner dialogs sparingly — they are meant for global messages and should not stack
- Always include a close button in the top right in corner dialogs
- Always include a primary button in corner dialogs
- Place primary buttons to the right of other buttons
Don't
- Include a top right close button, except if: you can't use
lightDismiss, there isn't a cancel button in the dialog’s footer, and/or it’s a corner dialog
Developer guidance
Corner dialogs
Don't use corner dialogs directly. Use the Global Messages Service instead:
this.messagesService = context.pageContext.getService<IGlobalMessagesService>("IGlobalMessagesService");
this.messagesService.addDialog({
message: "New Corner Dialog",
title: "Dialog Title"
buttonProps: [{ primary: true, text: "Accept" }]
});
APIs
ICustomDialogProps
ariaDescribedByInherited From: ICalloutProps
string
Id of another element which describes this one for screen reader users.
ariaLabelInherited From: ICalloutProps
string
ariaLabel allows the root element to describe the elements contents to assistive
technology.
ariaLabelledByInherited From: ICalloutProps
string
Id of another element which labels this one for screen reader users.
Defaults to this checkbox's label element.
blurDismissfalseInherited From: ICalloutProps
boolean
This will dismiss the callout once it gets and then loses focus. Callouts should
dismiss when they lose focus unless they are intended to be modeless UI.
calloutClassName
string
CSS className that should be applied to the top level callout element.
calloutContentClassName
string
CSS className that should be applied to the callout's content element.
className
string
An optional className to pass to the root dialog element.
contentJustificationInherited From: ICalloutProps
Justification of the callout content within the callout. This defaults to auto
layout and will take on the content size. This ONLY applies to window relative
layouts, use contentLocation to use this.
contentLocationInherited From: ICalloutProps
This needs to be supplied for a window relative layout. Otherwise the anchorElement
is used as the location basis.
contentSizeInherited From: ICalloutProps
If supplied there are a set of well-known fixed size callout's designed to keep
things like panels and other types of information using a consistent layout.
This ONLY applies to window relative layouts, use contentLocation to use this.
This should be supplied when you are following a standard UI model size.
defaultActiveElement
string | (() => string)
Element selector of the first focusable element. If no selector is supplied, a hidden
element will be created and focus given to the CommandBarFlyout through this element.
defaultFocusableElementAriaLabel
string
/**
* Method that is called when the dialog is dismissed.
*/
onDismiss: () => void
Aria-label for the default focusable element if defaultActiveElement isn't provided.
enterPrimary
boolean
The dialog will handle keyboard events and when the enter key is pressed the
dialog will behave as if the primary key was pressed if the event
hasnt had the defaultPrevented.
escDismissInherited From: ICalloutProps
boolean
The callout will handle keyboard events and when the escape key is pressed the
callout will close if the the event hasnt had the defaultPrevented.
idInherited From: ICalloutProps
string
If the id supplied, this id will be added to the callout element as the DOM
id attribute.
lightDismissInherited From: ICalloutProps
boolean
The callout element will trap mouse events and dismiss the callout when a click
occurs. This will prevent the events from being handled by the underlying
elements outside the callout's contents.
modalInherited From: ICalloutProps
boolean
The callout element will be given a class that is a semi-transparency that helps
the user understand the user should focus on the callout and dismiss it before
interacting with the underlying document.
overlay
{
spinnerLabel?: string;
spinnerAriaLabel?: string;
}
If set, the content of the dialog will be overlaid with a transparent div with a spinner.
resizable
boolean
If true, the dialog will have a gripper in the corner that can be used to resize.
roleInherited From: ICalloutProps
string
role is used to define the assistive usage of this callout. The default is
"dialog", but can be overriden with this property.
selectInputTextOnFocus
boolean
If true, while tabbing through dialog elements if ends up on input element than text
will be selected automatically. This is a default input behavior.
IDialogProps
ariaDescribedByInherited From: ICalloutProps
string
Id of another element which describes this one for screen reader users.
ariaLabelInherited From: ICalloutProps
string
ariaLabel allows the root element to describe the elements contents to assistive
technology.
ariaLabelledByInherited From: ICalloutProps
string
Id of another element which labels this one for screen reader users.
Defaults to this checkbox's label element.
blurDismissfalseInherited From: ICalloutProps
boolean
This will dismiss the callout once it gets and then loses focus. Callouts should
dismiss when they lose focus unless they are intended to be modeless UI.
calloutClassNameInherited From: ICustomDialogProps
string
CSS className that should be applied to the top level callout element.
calloutContentClassNameInherited From: ICustomDialogProps
string
CSS className that should be applied to the callout's content element.
classNameInherited From: ICustomDialogProps
string
An optional className to pass to the root dialog element.
contentJustificationInherited From: ICalloutProps
Justification of the callout content within the callout. This defaults to auto
layout and will take on the content size. This ONLY applies to window relative
layouts, use contentLocation to use this.
contentLocationInherited From: ICalloutProps
This needs to be supplied for a window relative layout. Otherwise the anchorElement
is used as the location basis.
contentSizeInherited From: ICalloutProps
If supplied there are a set of well-known fixed size callout's designed to keep
things like panels and other types of information using a consistent layout.
This ONLY applies to window relative layouts, use contentLocation to use this.
This should be supplied when you are following a standard UI model size.
defaultActiveElementInherited From: ICustomDialogProps
string | (() => string)
Element selector of the first focusable element. If no selector is supplied, a hidden
element will be created and focus given to the CommandBarFlyout through this element.
defaultFocusableElementAriaLabelInherited From: ICustomDialogProps
string
/**
* Method that is called when the dialog is dismissed.
*/
onDismiss: () => void
Aria-label for the default focusable element if defaultActiveElement isn't provided.
enterPrimaryInherited From: ICustomDialogProps
boolean
The dialog will handle keyboard events and when the enter key is pressed the
dialog will behave as if the primary key was pressed if the event
hasnt had the defaultPrevented.
escDismissInherited From: ICalloutProps
boolean
The callout will handle keyboard events and when the escape key is pressed the
callout will close if the the event hasnt had the defaultPrevented.
idInherited From: ICalloutProps
string
If the id supplied, this id will be added to the callout element as the DOM
id attribute.
lightDismissInherited From: ICalloutProps
boolean
The callout element will trap mouse events and dismiss the callout when a click
occurs. This will prevent the events from being handled by the underlying
elements outside the callout's contents.
modalInherited From: ICalloutProps
boolean
The callout element will be given a class that is a semi-transparency that helps
the user understand the user should focus on the callout and dismiss it before
interacting with the underlying document.
overlayInherited From: ICustomDialogProps
{
spinnerLabel?: string;
spinnerAriaLabel?: string;
}
If set, the content of the dialog will be overlaid with a transparent div with a spinner.
resizableInherited From: ICustomDialogProps
boolean
If true, the dialog will have a gripper in the corner that can be used to resize.
roleInherited From: ICalloutProps
string
role is used to define the assistive usage of this callout. The default is
"dialog", but can be overriden with this property.
selectInputTextOnFocusInherited From: ICustomDialogProps
boolean
If true, while tabbing through dialog elements if ends up on input element than text
will be selected automatically. This is a default input behavior.
showCloseButton
boolean
Shows a close button in the top right corner of the dialog. Using a cancel button in
the footer or lightDismiss are preferred over this.