Button
Render buttons with custom functionality in your form for conditional logic and branching paths.
Buttons allow users to trigger custom Python functions, processing or different form behaviors. When a button is pressed, its key becomes True in the form state, enabling conditional logic to determine the next steps in your workflow. This makes buttons essential for creating approval workflows, multi-path forms, and interactive decision trees.
Unlike automatic navigation buttons (NextButton/BackButton), custom Button widgets give you full control over widget behavior within a page and can be used to implement complex conditional logic based on user choices.
How Button State Works
When a user clicks a button, the button's key is set to True in the form state. You can then check this state using state.get("button_key") to determine which button was pressed and conditionally render different widgets or forms.
Usage Pattern
Buttons are optionally returned from your Page function (a function that returns a list of widgets). You have two options:
Option 1: Return only widgets (default behavior)
Option 2: Return widgets + custom buttons as a tuple
If you don't return buttons (Option 1), the system automatically provides default navigation buttons (Next/Back). If you want custom buttons, you must return a tuple with widgets as the first element and a list of Button objects as the second element.
Common Use Cases
- Approval Workflows: Create "Approve" and "Reject" buttons for document review processes
- Data Reload: Refresh page content with updated information from external APIs or databases
- Multi-path Forms: Allow users to choose between different information collection paths
- Decision Trees: Build complex conditional forms based on user choices
- Custom Navigation: Implement non-linear form progression with custom logic
Examples
Custom Decision Buttons
Use custom buttons to create approval workflows with conditional logic based on user decisions
Example Code
Multi-Step Form Navigation
Use custom buttons to create branching form paths where different buttons lead to different form sections
Example Code
Data Reload with Button
Use custom buttons to refresh page content with updated data from external sources or calculations
Example Code
Parameters
| Name | Description | Type | Default |
|---|---|---|---|
| label (required) | The text displayed on the button. | str | None |
| key | An optional key for the button. If not provided, the label will be used as the key. | str | None |