Quick search

Button Behavior

The ButtonBehavior mixin class provides Button behavior. You can combine this class with other widgets, such as an Image, to provide alternative buttons that preserve Kivy button behavior.

For an overview of behaviors, please refer to the behaviors documentation.


The following example adds button behavior to an image to make a checkbox that behaves like a button:

from import App
from kivy.uix.image import Image
from kivy.uix.behaviors import ButtonBehavior

class MyButton(ButtonBehavior, Image):
    def __init__(self, **kwargs):
        super(MyButton, self).__init__(**kwargs)
        self.source = 'atlas://data/images/defaulttheme/checkbox_off'

    def on_press(self):
        self.source = 'atlas://data/images/defaulttheme/checkbox_on'

    def on_release(self):
        self.source = 'atlas://data/images/defaulttheme/checkbox_off'

class SampleApp(App):
    def build(self):
        return MyButton()


See ButtonBehavior for details.

class kivy.uix.behaviors.button.ButtonBehavior(**kwargs)[source]

Bases: builtins.object

This mixin class provides Button behavior. Please see the button behaviors module documentation for more information.


Fired when the button is pressed.


Fired when the button is released (i.e. the touch/click that pressed the button goes away).


This determines whether or not the widget fires an on_release event if the touch_up is outside the widget.

New in version 1.9.0.

Changed in version 1.10.0: The default value is now False.

always_release is a BooleanProperty and defaults to False.


Contains the last relevant touch received by the Button. This can be used in on_press or on_release in order to know which touch dispatched the event.

New in version 1.8.0.

last_touch is a ObjectProperty and defaults to None.


The minimum period of time which the widget must remain in the ‘down’ state.

New in version 1.9.1.

min_state_time is a float and defaults to 0.035. This value is taken from Config.


The state of the button, must be one of ‘normal’ or ‘down’. The state is ‘down’ only when the button is currently touched/clicked, otherwise its ‘normal’.

state is an OptionProperty and defaults to ‘normal’.


Trigger whatever action(s) have been bound to the button by calling both the on_press and on_release callbacks.

This is similar to a quick button press without using any touch events, but note that like most kivy code, this is not guaranteed to be safe to call from external threads. If needed use Clock to safely schedule this function and the resulting callbacks to be called from the main thread.

Duration is the length of the press in seconds. Pass 0 if you want the action to happen instantly.

New in version 1.8.0.