A button that can be pressed or clicked.



A button has a text label. A handler can be associated with button press events.

import toga

def my_callback(button):
    # handle event

button = toga.Button("Click me", on_press=my_callback)


  • A background color of TRANSPARENT will be treated as a reset of the button to the default system color.

  • On macOS, the button text color cannot be set directly; any color style directive will be ignored. The text color is automatically selected by the platform to contrast with the background color of the button.


class toga.Button(text, id=None, style=None, on_press=None, enabled=True)#

Bases: Widget

Create a new button widget.

  • text (Optional[str]) – The text to display on the button.

  • id (Optional[str]) – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

  • on_press (Optional[OnPressHandler]) – A handler that will be invoked when the button is pressed.

  • enabled (bool) – Is the button enabled (i.e., can it be pressed?). Optional; by default, buttons are created in an enabled state.

property on_press: OnPressHandler#

The handler to invoke when the button is pressed.

property text: str#

The text displayed on the button.

None, and the Unicode codepoint U+200B (ZERO WIDTH SPACE), will be interpreted and returned as an empty string. Any other object will be converted to a string using str().

Only one line of text can be displayed. Any content after the first newline will be ignored.

protocol toga.widgets.button.OnPressHandler#


Classes that implement this protocol must have the following methods / attributes:

__call__(widget, **kwargs)#

A handler that will be invoked when a button is pressed.


**kwargs ensures compatibility with additional arguments introduced in future versions.


widget (Button) – The button that was pressed.

Return type: