duck.html.components.extensions.clickable.ripple

Ripple extension for HTML components.

Gives a container component a Material-style press ripple: a translucent circle that grows from the pointer position and fades out once released, for a native touch feel.

Usage example:

from duck.html.components.button import Button
from duck.html.components.extensions.clickable import RippleExtension

class RippleButton(RippleExtension, Button):
    pass

btn = RippleButton(text="Save", ripple_color="rgba(255, 255, 255, 0.4)")

Keyword arguments:

  • ripple_color (str): CSS color of the ripple. Defaults to the text color.

  • ripple_duration (int): Time in milliseconds the ripple takes to fully grow.

  • ripple_centered (bool): Start every ripple from the center (e.g. icon buttons).

Notes:

  • The component must be able to contain children, so void elements are rejected.

  • The host gets position: relative and overflow: hidden unless you set them.

  • No ripple is shown once the press turns into a scroll or swipe.

  • The ripple never calls preventDefault or stopPropagation, and its DOM write is deferred a couple of frames, so the underlying component’s own click listeners keep firing normally.

Module Contents

Classes

RippleExtension

Extension adding a native-style press ripple to container components.

Data

CENTERED_ATTRIBUTE

COLOR_VARIABLE

DEFAULT_DURATION_MS

DURATION_ATTRIBUTE

EXPAND_EASING

FADE_DURATION_MS

HOST_CLASS

HOST_STYLE_DEFAULTS

READY_FLAG

RIPPLE_SCRIPT

RIPPLE_STYLE

SCRIPT_TEMPLATE

SCROLL_MOVE_THRESHOLD_PX

STYLE_ELEMENT_ID

STYLE_TEMPLATE

TEMPLATE_VALUES

WAVE_CLASS

WAVE_OPACITY

API

duck.html.components.extensions.clickable.ripple.CENTERED_ATTRIBUTE

‘data-ripple-centered’

duck.html.components.extensions.clickable.ripple.COLOR_VARIABLE

‘–duck-ripple-color’

duck.html.components.extensions.clickable.ripple.DEFAULT_DURATION_MS

550

duck.html.components.extensions.clickable.ripple.DURATION_ATTRIBUTE

‘data-ripple-duration’

duck.html.components.extensions.clickable.ripple.EXPAND_EASING

‘cubic-bezier(0.4, 0, 0.2, 1)’

duck.html.components.extensions.clickable.ripple.FADE_DURATION_MS

300

duck.html.components.extensions.clickable.ripple.HOST_CLASS

‘duck-ripple’

duck.html.components.extensions.clickable.ripple.HOST_STYLE_DEFAULTS

None

duck.html.components.extensions.clickable.ripple.READY_FLAG

‘duckRippleReady’

duck.html.components.extensions.clickable.ripple.RIPPLE_SCRIPT

‘substitute(…)’

duck.html.components.extensions.clickable.ripple.RIPPLE_STYLE

‘substitute(…)’

class duck.html.components.extensions.clickable.ripple.RippleExtension[source]

Bases: duck.html.components.extensions.Extension

Extension adding a native-style press ripple to container components.

The component only carries a class, a few attributes and one small script. The script installs the wave styles and a single delegated pointer handler the first time it runs, so ripples also work on components added later.

add_ripple_extension_script()[source]

Adds ripple extension script to component or component’s parent.

apply_extension() → None[source]

Apply the ripple effect to the component.

Marks the component as a ripple host, applies the ripple options from kwargs and attaches the script that drives the animation.

apply_ripple_extension_host_style() → None[source]

Mark the component as a ripple host and give it a clipping box.

The wave is absolutely positioned and must be clipped by the host, so the host needs a positioned box with hidden overflow. Values the component has already set are kept.

apply_ripple_extension_options() → None[source]

Apply the ripple options from kwargs.

The color goes through a CSS variable read by the wave styles, while the duration and origin are attributes read by the script on every press.

load()[source]

Load component, modified by RippleExtension.

duck.html.components.extensions.clickable.ripple.SCRIPT_TEMPLATE = <Multiline-String>
duck.html.components.extensions.clickable.ripple.SCROLL_MOVE_THRESHOLD_PX

10

duck.html.components.extensions.clickable.ripple.STYLE_ELEMENT_ID

‘duck-ripple-style’

duck.html.components.extensions.clickable.ripple.STYLE_TEMPLATE = <Multiline-String>
duck.html.components.extensions.clickable.ripple.TEMPLATE_VALUES

None

duck.html.components.extensions.clickable.ripple.WAVE_CLASS

‘duck-ripple-wave’

duck.html.components.extensions.clickable.ripple.WAVE_OPACITY

0.25