Touch Ripple

New in version 1.10.1.


This code is still experimental, and its API is subject to change in a future version.

This module contains mixin classes to add a touch ripple visual effect known from Google Material Design <>_ to widgets.

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

The class TouchRippleBehavior provides rendering the ripple animation.

The class TouchRippleButtonBehavior basically provides the same functionality as ButtonBehavior but rendering the ripple animation instead of default press/release visualization.

class kivy.uix.behaviors.touchripple.TouchRippleBehavior(**kwargs)[source]

Bases: builtins.object

Touch ripple behavior.

Supposed to be used as mixin on widget classes.

Ripple behavior does not trigger automatically, concrete implementation needs to call ripple_show() respective ripple_fade() manually.


Here we create a Label which renders the touch ripple animation on interaction:

class RippleLabel(TouchRippleBehavior, Label):

    def __init__(self, **kwargs):
        super(RippleLabel, self).__init__(**kwargs)

    def on_touch_down(self, touch):
        collide_point = self.collide_point(touch.x, touch.y)
        if collide_point:
            return True
        return False

    def on_touch_up(self, touch):
        if touch.grab_current is self:
            return True
        return False

Animation duration taken to show the overlay.

ripple_duration_in is a NumericProperty and defaults to 0.5.


Animation duration taken to fade the overlay.

ripple_duration_out is a NumericProperty and defaults to 0.2.


Finish ripple animation on current widget.


Alpha channel for ripple color the animation starts with.

ripple_fade_from_alpha is a NumericProperty and defaults to 0.5.


Alpha channel for ripple color the animation targets to.

ripple_fade_to_alpha is a NumericProperty and defaults to 0.8.


Animation callback for showing the overlay.

ripple_func_in is a StringProperty and defaults to in_cubic.


Animation callback for hiding the overlay.

ripple_func_out is a StringProperty and defaults to out_quad.


Default radius the animation starts from.

ripple_rad_default is a NumericProperty and defaults to 10.


Max scale of the animation overlay calculated from max(width/height) of the decorated widget.

ripple_scale is a NumericProperty and defaults to 2.0.


Begin ripple animation on current widget.

Expects touch event as argument.

class kivy.uix.behaviors.touchripple.TouchRippleButtonBehavior(**kwargs)[source]

Bases: kivy.uix.behaviors.touchripple.TouchRippleBehavior

This mixin class provides a similar behavior to ButtonBehavior but provides touch ripple animation instead of button pressed/released as visual effect.


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.

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.

last_touch is a ObjectProperty and defaults to None.