dialog

A modal dialog.

Dialog allows showing some content over the current page. The dialog can be closed when the user presses the Cancel or Validate buttons, or clicks outside the area of the dialog (triggering a Cancel action).

Properties

Name	Type	Default	Description
open(★)	bool	False	If True, the dialog is visible. If False, it is hidden.
on_action	Union[str, Callable]		A function or the name of a function triggered when a button is pressed. This function is invoked with the following parameters: state (State): the state instance. id (str): the identifier of the dialog if it has one. payload (dict): the details on this callback's invocation. This dictionary has the following keys: action: the name of the action that triggered this callback. args: a list where the first element contains the index of the selected label.
close_label	str	"Close"	The tooltip of the top-right close icon button. In the on_action callback, args will be set to -1.
labels	Union[str,list[str]]		A list of labels to show in a row of buttons at the bottom of the dialog. The index of the button in the list is reported as args in the on_action callback (that index is -1 for the close icon).
width	Union[str,int,float]		The width of this dialog, in CSS units.
height	Union[str,int,float]		The height of this dialog, in CSS units.
page	str		The page name to show as the content of the block. This should not be defined if partial is set.
partial	taipy.gui.Partial		A Partial object that holds the content of the block. This should not be defined if page is set.
active	bool dynamic	True	Indicates if this component is active. An inactive component allows no user interaction.
id	str		The identifier that is assigned to the rendered HTML component.
properties	dict[str, Any]		Bound to a dictionary that contains additional properties for this element.
class_name	str dynamic		The list of CSS class names that are associated with the generated HTML Element. These class names are added to the default taipy-dialog class name.
hover_text	str dynamic		The information that is displayed when the user hovers over this element.

^(★)open is the default property for this visual element.

Details

The dialog element is used to communicate information to the user or to gather input. It typically appears as a small window over the main content, prompting the user to make decisions or provide information. Dialogs are commonly used in applications for actions such as confirming operations, requesting input, or displaying status updates.

Dialogs can contain any type of visual elements, including text, buttons, and so on.
Buttons can be generated automatically within the dialog, based on the dialog configuration.

To add elements to a dialog, you must use block syntax in your code:

Definition

MarkdownHTMLPython

<|{is_opened}|dialog|
... more visual elements
... e.g.
<|Hello|>
<|Confirm|button|>
|>

<taipy:dialog>{is_opened}
  <!-- more visual elements -->
  <!-- e.g. -->
  <taipy:text>Hello</taipy:text>
  <taipy:button>Confirm</taipy:button>
</taipy:dialog>

import taipy.gui.builder as tgb
...
with tgb.dialog("{is_opened}")
    # more visual elements
    # e.g.
    tgb.text("Hello")
    tgb.button("Confirm")

In this example, the dialog is opened or closed based on the value of the is_opened variable. The dialog contains a text element and a button labeled "Confirm."

The content of a dialog can also be defined using Pages or Partials, allowing for the reuse of UI components and better organization of the code.

Usage

Showing or hiding a dialog

See the entire code for this example

The open property of a dialog determines whether the dialog is visible. This property is usually bound to a Boolean variable. For example:

show_dialog = False

When the user interacts with the dialog, the function set to the on_action property is triggered. Typically, the dialog should close when the user presses the close button (the "X" in the top-right corner). Here's the definition of the function to handle this:

def hide(state):
    state.show_dialog = False

This function closes the dialog by setting its open property to False.

Here is the definition of the dialog that references the show_dialog variable and the hide() callback function:

Definition

MarkdownHTMLPython

<|{show_dialog}|dialog|on_action=hide|>

Note that

<taipy:dialog on_action="hide">{show_dialog}</taipy:dialog>

import taipy.gui.builder as tgb
...
tgb.dialog("{show_dialog}", on_action=hide)

Since the hide() function is straightforward, it can be replaced by a lambda function:
tgb.dialog("{show_dialog}", on_action=lambda s: s.assign("show_dialog", False))
With this line, the dialog action is defined as a lambda function that sets show_dialog to False, effectively closing the dialog. The hide() is not needed any longer.

To open the dialog, the show_dialog variable must be set to True. This can be done using a callback function triggered by another control (e.g., a button).
Here is the definition of this callback function:

def show(state):
    state.show_dialog = True

Below is an example of the dialog's appearance when no content is added inside it:

Empty dialog

Since no elements were added to the dialog, it appears empty.
However, the dialog can still be interacted with, and it will disappear when the close button is pressed.

Specifying labels and actions

See the entire code for this example

The labels property can be set to a list of strings (or a semi-colon-separated string, which Taipy GUI automatically converts into a list). Each element in this list becomes the label of a button. These buttons are displayed at the bottom of the dialog, arranged in a row.

The callback function set to the on_action property is invoked when any of the buttons is pressed. You can determine which button was pressed using the callback's payload parameter, as shown below.

Here is an example of a dialog that generates a series of buttons:

Definition

MarkdownHTMLPython

<|{show_dialog}|dialog|title=Welcome!|labels=Couldn't be better;Not my day|on_action=dialog_action|>

<taipy:dialog title="Welcome!" labels="Couldn't be better;Not my day" on_action="dialog_action">{show_dialog}</taipy:dialog>

import taipy.gui.builder as tgb
...
tgb.dialog("{show_dialog}", title="Welcome!", labels="Couldn't be better;Not my day", on_action=dialog_action)

This definition indicates that:

• The dialog is visible or hidden depending on the value of show_dialog;
• The dialog will display the title "Welcome!".
• Two buttons must be created at the bottom of the dialog: "Couldn't be better" and "Not my day".
• When any button or the close button is pressed, the dialog_action() callback function is invoked.

Here’s how you can implement the dialog_action() function to handle the button presses:

def dialog_action(state, _, payload):
    if payload["args"][0] == 0:  # The first button was pressed
        ...
    elif payload["args"][0] == 1:  # The second button was pressed
        ...
    else:  # The dialog's Close button was pressed (index == -1)
        ...
    state.show_dialog = False

The payload["args"][0] value indicates which button was pressed:

• 0: The first button ("Couldn't be better") was pressed.
• 1: The second button ("Not my day") was pressed.
• -1: The Close button of the dialog was pressed.

In all cases, the dialog is closed by setting state.show_dialog to False.

When show_dialog is set to True, the dialog will display two buttons at the bottom:

Automatic buttons

If the user presses the first button, "COULDN'T BE BETTER", the dialog_action() callback function is invoked with payload["args"][0] set to 0.

Dialog with page

The content of the dialog can be specified as an existing page name using the page property.

Definition

MarkdownHTMLPython

<|{show_dialog}|dialog|page=page_name|>

<taipy:dialog page="page_name">{show_dialog}</taipy:dialog>

import taipy.gui.builder as tgb
...
tgb.dialog("{show_dialog}", page="page_name")

Dialog with partial

The content of the dialog can be specified as a Partial instance using the partial property.

Definition

MarkdownHTMLPython

<|{show_dialog}|dialog|partial={partial}|>

<taipy:dialog partial="{partial}">{show_dialog}</taipy:dialog>

import taipy.gui.builder as tgb
...
tgb.dialog("{show_dialog}", partial="{partial}")

Styling

All the dialogs are generated with the "taipy-dialog" CSS class. You can use this class name to select the dialogs on your page and apply style.