Logo

ModalDialog

ModalDialog creates overlay dialogs that appear on top of the main interface, ideal for forms, confirmations, detailed views, or any content that requires focused user attention. Dialogs are programmatically opened using the open() method and can receive parameters for dynamic content.
Key features:
  • Overlay presentation: Appears above existing content with backdrop dimming
  • Programmatic control: Open and close via exposed methods like open() and close()
  • Parameter passing: Accept data when opened for dynamic dialog content
  • Focus management: Automatically handles focus trapping and accessibility
  • Form integration: When containing Form components, automatically closes on form submission or cancellation (unless overridden)

Using the Component

When using the examples in this article, pop them out to the full screen to check how they work.
Opening and closing the modal dialog can be done in two ways depending on circumstances.

With Imperative API

Event-driven display of the ModalDialog dialog is also possible using imperative API.
This method is a good way to toggle the display of the ModalDialog if no deep linking is necessary. It also lends to itself that these events can be triggered programmatically from codebehind.
Note the id property of the ModalDialog in the example below and how it is used to call the open and close operations of the component in the onClick event handlers.
<App>
  <ModalDialog id="dialog" title="Example Dialog">
    <Button label="Close Dialog" onClick="dialog.close()" />
  </ModalDialog>
  <Button label="Open Dialog" onClick="dialog.open()" />
</App>
Example: imperative API
<App>
  <ModalDialog id="dialog" title="Example Dialog">
    <Button label="Close Dialog" onClick="dialog.close()" />
  </ModalDialog>
  <Button label="Open Dialog" onClick="dialog.open()" />
</App>
The imperative approach is perhaps the most intuitive way to display and hide modal dialogs.

With when

The when property accepts a primitive boolean or a binding expression resolving to a boolean value to toggle the display of a component.
Using the when property in a ModalDialog dialog component is commonly used with deep linking: showing the modal in conjunction with an updated URL so that the opened state of the modal dialog is referable.
<App>
  <variable name="isDialogShown" value="{false}"/>
  <Button label="Open Dialog" onClick="isDialogShown = true" />
  <ModalDialog 
    when="{isDialogShown}" 
    title="Example Dialog" 
    onClose="isDialogShown = false" />
</App>
Click on the button in the demo below to open the modal dialog. Click anywhere outside the opened dialog or the close button to close it.
<App>
  <variable name="isDialogShown" value="{false}"/>
  <Button label="Open Dialog" onClick="isDialogShown = true" />
  <ModalDialog 
    when="{isDialogShown}" 
    title="Example Dialog" 
    onClose="isDialogShown = false" />
</App>
Click on the button in the demo below to open the modal dialog. Click anywhere outside the opened dialog or the close button to close it.
Setting the when property is the most straightforward way for deep-linked modals. If you use deep links with query parameters to show a particular dialog, you can set the when property to show or hide the dialog according to parameter values.

The ModalDialog as a Container

The ModalDialog component is also a container such as the Card, that it also accepts child components.
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Dialog">
    <Form data="{{ firstName: 'Billy', lastName: 'Bob' }}">
      <FormItem bindTo="firstName" required="true" />
      <FormItem bindTo="lastName" required="true" />
    </Form>
  </ModalDialog>
</App>
Example: children
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Dialog">
    <Form data="{{ firstName: 'Billy', lastName: 'Bob' }}">
      <FormItem bindTo="firstName" required="true" />
      <FormItem bindTo="lastName" required="true" />
    </Form>
  </ModalDialog>
</App>
When a form is nested into a modal dialog, closing the form (canceling it or completing its submit action) automatically closes the dialog.
Context variables available during execution:
  • $param: First parameter passed to the open() method
  • $params: Array of all parameters passed to open() method (access with $params[0], $params[1], etc.)

Properties

closeButtonVisible (default: true)

Shows (true) or hides (false) the visibility of the close button on the dialog.
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" closeButtonVisible="false" title="Example Dialog" />
</App>
Click outside the dialog to close it.
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" closeButtonVisible="false" title="Example Dialog" />
</App>
Click outside the dialog to close it.

fullScreen (default: false)

Toggles whether the dialog encompasses the whole UI (true) or not and has a minimum width and height (false).
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" fullScreen="true" title="Example Dialog" />
</App>
Click the button to display a full-screen dialog. The icon at the top-right corner of the dialog allows you to close it.
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" fullScreen="true" title="Example Dialog" />
</App>
Click the button to display a full-screen dialog. The icon at the top-right corner of the dialog allows you to close it.

title

Provides a prestyled heading to display the intent of the dialog.
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Title" />
</App>
Example: title
<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Title" />
</App>

Events

close

This event is fired when the close button is pressed or the user clicks outside the ModalDialog.
In this example, the close event counts how many times you closed the dialog:
<App>
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onClose="counter++">
    <Text value="Dialog closed {counter} number of times." />
  </ModalDialog>
</App>
Open and close the dialog several times to test that it changes the counter.
<App>
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onClose="counter++">
    <Text value="Dialog closed {counter} number of times." />
  </ModalDialog>
</App>
Open and close the dialog several times to test that it changes the counter.

open

This event is fired when the ModalDialog is opened either via a when or an imperative API call (open()).
In this example, the open event counts how many times you opened the dialog:
<App>
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onOpen="counter++">
    <Text value="Dialog opened {counter} number of times." />
  </ModalDialog>
</App>
Open and close the dialog several times to test that it changes the counter.
<App>
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onOpen="counter++">
    <Text value="Dialog opened {counter} number of times." />
  </ModalDialog>
</App>
Open and close the dialog several times to test that it changes the counter.

Exposed Methods

close

This method is used to close the ModalDialog. Invoke it using modalId.close() where modalId refers to a ModalDialog component.
Signature: close(): void See the `With Imperative API` subsection for an example.

open

This method imperatively opens the modal dialog. You can pass an arbitrary number of parameters to the method. In the ModalDialog instance, you can access those with the $param and $params context values.
Signature: open(...params: any[]): void
  • params: An arbitrary number of parameters that can be used to pass data to the dialog.
See the `With Imperative API` subsection for an example.

Styling

Theme Variables

VariableDefault Value (Light)Default Value (Dark)
backgroundColor-ModalDialog$backgroundColor-primary$backgroundColor-primary
backgroundColor-ModalDialog$backgroundColor-primary$backgroundColor-primary
backgroundColor-overlay-ModalDialog$backgroundColor-overlay$backgroundColor-overlay
backgroundColor-overlay-ModalDialog$backgroundColor-overlay$backgroundColor-overlay
borderRadius-ModalDialog$borderRadius$borderRadius
borderRadius-ModalDialog$borderRadius$borderRadius
fontFamily-ModalDialog$fontFamily$fontFamily
fontFamily-ModalDialog$fontFamily$fontFamily
marginBottom-title-ModalDialog00
marginBottom-title-ModalDialog00
maxWidth-ModalDialog450px450px
maxWidth-ModalDialog450px450px
minWidth-ModalDialognonenone
padding-ModalDialog$space-7$space-7
padding-overlay-ModalDialognonenone
paddingBottom-ModalDialog$paddingVertical-ModalDialog$paddingVertical-ModalDialog
paddingBottom-overlay-ModalDialognonenone
paddingHorizontal-ModalDialognonenone
paddingHorizontal-overlay-ModalDialognonenone
paddingLeft-ModalDialog$paddingHorizontal-ModalDialog$paddingHorizontal-ModalDialog
paddingLeft-overlay-ModalDialognonenone
paddingRight-ModalDialog$paddingHorizontal-ModalDialog$paddingHorizontal-ModalDialog
paddingRight-overlay-ModalDialognonenone
paddingTop-ModalDialog$paddingVertical-ModalDialog$paddingVertical-ModalDialog
paddingTop-overlay-ModalDialognonenone
paddingVertical-ModalDialognonenone
paddingVertical-overlay-ModalDialognonenone
textColor-ModalDialog$textColor-primary$textColor-primary
textColor-ModalDialog$textColor-primary$textColor-primary
This site is an XMLUI™ app.