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>

<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>

<App>
  <variable name="isDialogShown" value="{false}"/>
  <Button label="Open Dialog" onClick="isDialogShown = true" />
  <ModalDialog 
    when="{isDialogShown}" 
    title="Example Dialog" 
    onClose="isDialogShown = false" />
</App>

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>

<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.)

Behaviors

This component supports the following behaviors:

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>

<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" closeButtonVisible="false" title="Example Dialog" />
</App>

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>

<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" fullScreen="true" title="Example Dialog" />
</App>

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>

<App>
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Title" />
</App>

titleTemplate

A custom template to render the dialog title.

Events

close

This event is fired when the close button is pressed or the user clicks outside the ModalDialog.

Signature: close(): void

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>

<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

This event is fired when the ModalDialog is opened either via a when or an imperative API call (open()).

Signature: open(...params: any[]): void

• params: Parameters passed to the open() method, accessible via $param and $params context variables.

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>

<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>

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.

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• content: The main content area of the modal dialog.
• title: The title area of the modal dialog.

Styling

Theme Variables