Skip to content

button

A control that can trigger a function when pressed.

Properties

Name Type Default Description
label(★) Union[str,Icon]
dynamic
""

The label displayed in the button.

on_action Union[str, Callable]

A function or the name of a function that is triggered when the button is pressed.
This function is invoked with the following parameters:

  • state (State): the state instance.
  • id (str): the identifier of the button it it has one.
  • payload (dict): a dictionary that contains the key "action" set to the name of the action that triggered this callback.

width Union[str,int] None

The width of the button element.

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-button class name.

hover_text str
dynamic

The information that is displayed when the user hovers over this element.

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

Usage

Simple button

The label of the button, defined by the default property label of the button control, is displayed as the text on the button.

Below is an example of how to define a button:

Definition

<|Button Label|button|>
<taipy:button>Button Label</taipy:button>
import taipy.gui.builder as tgb
...
tgb.button("Button Label")

Here is how the button is displayed:

A simple button

Specific action callback

A button can specify a callback function to be invoked when it is pressed. By default, the global function on_action() is triggered by the on_action callback if it is defined, as described in the section on callbacks.

To define a custom callback function for a button press, you can set the on_action property to reference the specific callback function you want to invoke.

Here is an example of defining such a callback function, named button_pressed():

def button_pressed(state):
    # React to the button press action

You can then assign this function to the button's on_action property:

Definition

<|Button Label|button|on_action=button_pressed|>
<taipy:button on_action="button_pressed">Button Label</taipy:button>
import taipy.gui.builder as tgb
...
tgb.button("Button Label", on_action=button_pressed)

When the user presses the button, the callback function button_pressed() is triggered.

The appearance of the button remains the same, even with a callback function bound to it.

Action as a lambda function

A callback function can be defined as a lambda function to handle button actions.

Below is an example of defining a button using a lambda function for the on_action property:

Definition

<|Button Label|button|id=button1|on_action={lambda s, i, p: s.assign("text", f"button '{i}': '{p.get('action')}'.")}|>
<taipy:button id="button1" on_action="{lambda s, i, p: s.assign('text', f'button '{i}': '{p.get('action')}'.')}">Button Label</taipy:button>
import taipy.gui.builder as tgb
...
tgb.button("Button Label", id="button1", on_action=lambda s, i, p: s.assign("text", f"button '{i}': '{p.get('action')}'."))

The lambda function takes the same parameters as a standard on_action callback:

  • s (the state object),
  • i (the control id), and
  • p (a payload dictionary, where the "action" key holds the action name).

In this example, the lambda function sets the text variable to a string that includes the button's id and the action name.
This variable can be used by another control, and any change to its value triggers the on_change callback as expected.

Note that when using a lambda function, the action name may appear as a mangled symbol generated by the Python interpreter.

Using an icon

A button can contain text, an icon, or both.

To add an icon to a button, you must first create an instance of the Icon object, which represents the image and its associated label (text).

To add an icon to a button, you must create an Icon instance:

icon = Icon("charles-avatar.png", "Charles")

The variable icon contains the path path of the image file used as the icon (in this example, the file should be located in the same directory as the Python script) and the text label that will appear next to the icon.

Once you have created the icon instance, you can assign it to the button's label property:

Definition

<|{icon}|button|>
<taipy:button>{icon}</taipy:button>
import taipy.gui.builder as tgb
...
tgb.button("{icon}")

This will display both the image and the associated text ("Charles") on the button:

Icon in a button

Styling

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

Stylekit support

The Stylekit provides specific classes that you can use to style buttons:

  • secondary
    error
    warning
    success
    Buttons are normally displayed using the value of the color_primary Stylekit variable. These classes can be used to change the color used to draw the button, respectively, with the color_secondary, color_error, color_warning and color_success Stylekit variable values.

    The Markdown content:

    <|Error|button|class_name=error|><|Secondary|button|class_name=secondary|>
    

    Renders like this:

    Using color classes

  • plain
    The button is filled with a plain color rather than just outlined.

    The Markdown content:

    <|Button 1|button|><|Button 2|button|class_name=plain|>
    

    Renders like this:

    Using the plain class

  • fullwidth: The button is rendered on its own line and expands across the entire available width.

Customizing with CSS

You can apply all relevant CSS properties to customize the appearance of the button control.

We can add a specific CSS class to the button's definition:

Definition

<|Button Label|button|class_name=my-style|>
<taipy:button class_name="my-style">Button Label</taipy:button>
import taipy.gui.builder as tgb
...
tgb.button("Button Label", class_name="my-style")

This class can be used to create a CSS rule specifically for this button:

.taipy-button.my-style {
    border-radius: 0;
    color: green;
}

When this CSS rule is applied, the button will be styled as shown below:

Styling the button control

The corners of the button are no longer rounded (border-radius: 0) and the text color has been changed to green (color: green).