button
A control that can trigger a function when pressed.
Properties¶
Name | Type | Default | Description |
---|---|---|---|
(★) |
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.
|
|
width |
Union[str,int] |
None | The width of the button element. |
active |
bool dynamic |
True | Indicates if this component is active. |
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. |
|
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:


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:


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:


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