Introduction

This Flutter package allows developer to customize most of the behaviors and animations, with excellent performance and a touch effect package that can be controlled externally.

Event Type	Description	♾️ Async	♻️ Consecutive
Tap	When the user taps or clicks.	🟢	🔴
Double Tap	When the user double taps or double clicks.	🔴	🟢
Long Tap	When the user long tap or long press.	🔴	🟢
Drag(V, H)	Not support yet.	🟡	🟡

Preview

The gif image below may appear distorted and choppy due to compression.

Usage

The following explains the basic usage of this package.

How to apply the ripple effect?

Called when the user taps or clicks.

TouchRipple(
  onTap: () => print("Hello, World!"),
  child: ... // <- this your widget
)

How to perform an async task?

TouchRipple<String>(
    onTapAsync: () async {
        return await Future.delayed(const Duration(milliseconds: 500), () {
            return "end";
        });
    },
    onTapAsyncStart: () => print("start"),
    onTapAsyncEnd: print,
    // ... skip
);

How to define the style globally.

TouchRippleStyle defines the style of its descendant touch ripple widgets, similar to how PrimaryScrollController defines the controller for its descendant widgets.

TouchRippleStyle(
  rippleColor: Colors.blue.withAlpha(50),
  rippleBorderRadius: BorderRadius.circular(10),
  overlapBehavior: TouchRippleOverlapBehavior.ignore,
  cancelBehavior: TouchRippleCancelBehavior.none,
  onlyMainButton: false,
  tapBehavior: TouchRippleBehavior(...),
  child: ...
),

The Properties of TouchRipple

Name	Description	Type
onTap	The callback function is called when the user taps or clicks.	VoidCallback?
onTapAsync	The callback function is called when the user taps or clicks. but this function ensures that the touch ripple effect remains visible until the asynchronous operation is completed and prevents additional events during that time.	TouchRippleAsyncCallback<T>?
onTapAsyncStart	The callback function is called when an asynchronous operation is initiated by a tap. It provides the associated Future instance for the ongoing operation.	TouchRippleAsyncNotifyCallback<T>?
onTapAsyncEnd	The callback function is called when the result of the asynchronous operation is ready. It allows handling the result once the operation is complete.	TouchRippleAsyncResultCallback<T>?
onDoubleTap	The callback function is called when the user double taps or double clicks.	VoidCallback?
onDoubleTapConsecutive	The callback function is called to determine whether consecutive double taps should continue. It returns a bool indicating whether the long tap event should continue after the initial occurrence.	TouchRippleContinuableCallback?
onDoubleTapStart	The callback function is a lifecycle callback for the double-tap event. It is called when a double tap starts, which is useful for handling actions that occur during successive double taps.	VoidCallback?
onDoubleTapEnd	The callback function is a lifecycle callback for the double-tap event. It is called when a double tap ends, providing the advantage of knowing when a series of consecutive double taps has finished.	VoidCallback?
onLongTap	The callback function is called when the user long presses or long clicks.	TouchRippleContinuableCallback?
onLongTapStart	The callback function is a lifecycle callback for the long-tap event. It is called when a long tap starts, which is useful for initiating actions that require a sustained press.	VoidCallback?
onLongTapEnd	The callback function is a lifecycle callback for the long-tap event. It is called when a long tap ends, providing the advantage of knowing when a series of consecutive long taps has concluded.	VoidCallback?
onFocusStart	The callback function is a lifecycle callback for focus touch ripple events. It is called when a focus touch event starts, allowing for the initiation of actions based on the beginning of the focus event sequence.	VoidCallback?
onFocusEnd	The callback function is a lifecycle callback for focus touch ripple events. It is called when a focus touch event ends, providing the advantage of knowing when a series of focus touch ripple events has concluded.	VoidCallback?
onHoverStart	The callback function called when the cursor begins hovering over the widget. (by MouseRegion) This function allows for the initiation of actions based on the hover interaction. This function is not called in touch-based environments yet.	VoidCallback?
onHoverEnd	The callback function called when the cursor begins to leave the widget. (by MouseRegion) This function allows for actions to be executed based on the end of the hover interaction. This function is not called in touch-based environments yet.	VoidCallback?
hitBehavior	The behavior of hit testing for the child widget.	HitTestBehavior?
rippleColor	The background color of a spread ripple effect.	Color?
hoverColor	The background color of a effect when the user hovers.	Color?
focusColor	The background color of the solid effect when a consecutive (e.g. about double-tap and long-tap) event state occurs.	Color?
rippleScale	The scale percentage value of a ripple effect and by default the origin position is center.	double?
rippleBlurRadius	The radius pixels of a blur filter for spread ripple effect. It cannot be negative and as the value increases, the edge of the spread ripple effect becomes blurrier.	double?
rippleBorderRadius	The instance of a border radius for a ripple effect. For reference, this option can be replaced with a widget like ClipRRect depending on the situation.	BorderRadius?
previewDuration	The duration for which the ripple effect is previewed even if the gesture is not finalized, allowing the user to see the effect while the pointer is down or moving.	Duration?
tappableDuration	The duration after which the gesture is considered rejected if the pointer is still down and no tap is completed. If this duration elapses without a successful gesture, the gesture will be rejected.	Duration?
doubleTappableDuration	The minimum duration used to distinguish between a tap and a double-tap. If the user does not perform a second tap within this duration, it is considered just a single-tap.	Duration?
doubleTapAliveDuration	The duration until double-tap deactivation. During this period, any single tap is still considered a double-tap without requiring continuous double-tapping.	Duration?
longTappableDuration	The minimum duration used to distinguish between a tap and a long-tap. After this duration has passed, the long-tap effect starts to be displayed to the user.	Duration?
longTapCycleDuration	The duration until long-tap reactivation. After this period, any pointer down and move is still considered a long-tap without requiring the continuous process of pointer-up followed by pointer-down.	Duration?
tapBehavior	The touch ripple behavior applied to the touch ripple effect for tapped or clicked.	TouchRippleBehavior?
doubleTapBehavior	The touch ripple behavior applied to the touch ripple effect for double tapped or double clicked.	TouchRippleBehavior?
longTapBehavior	The touch ripple behavior applied to the touch ripple effect for long tapped or long pressed and long clicked.	TouchRippleBehavior?
rejectBehavior	The behavior that defines when a gesture should be rejected, specifying the conditions for rejection.	TouchRippleRejectBehavior?
cancelBehavior	The behavior that defines the touch ripple spread animation when the touch ripple effect is canceled.	TouchRippleCancelBehavior?
overlapBehavior	The behavior of a touch ripple when it overlaps with other ripple effects. (e.g. overlappable, cancel, ignore)	TouchRippleOverlapBehavior?
renderOrderType	The enumeration specifies the rendering order of the touch ripple effect, determining whether it should appear in the foreground or background.	TouchRippleRenderOrderType?
focusTiming	The enumeration defines when the focus of a touch ripple should start, specifying the priority based on timing conditions.	TouchRippleFocusTiming?
origin	The enumeration defines the starting point of a spread ripple effect, specifying the origin of the ripple based on the user interaction.	TouchRippleOrigin?
hoverAnimation	The instance of the fade animation for the touch ripple effect when the hover effect is triggered.	TouchRippleAnimation?
focusAnimation	The instance of the fade animation for the touch ripple effect when the focus effect is triggered.	TouchRippleAnimation?
onlyMainButton	The boolean that is whether only the main button is recognized as a gesture when the user that is using mouse device clicks on the widget.	bool?
useHoverEffect	Whether the hover effect is enabled for touch ripple animations. If true, a solid hover effect is applied when the user hovers.	bool?
useFocusEffect	Whether the focus effect is enabled for touch ripple animations. If true, a solid focus color effect is applied for consecutive events like double-tap and long-tap or others.	bool?
controller	The controller defines and manages states, listeners, a context and other values related to touch ripple, ensuring that each state exists uniquely within the controller.	TouchRippleController?
child	The widget that is target to apply touch ripple related effects.	Widget

The Properties of TouchRippleRejectBehavior

The enumeration defines when a gesture should be rejected, specifying the conditions for rejection.

Name	Description
none	Sets the gesture to not be rejected regardless of any action or event. However, if the gesture is forcibly rejected due to a scroll gesture, the rejection will occur as expected.
touchSlop	Sets the gesture to be canceled if the pointer movement distance is greater than or equal to kTouchSlop.
leave	Sets the gesture to be canceled if the pointer position is outside the area occupied by the widget.

When TouchRippleRejectBehavior.none

When TouchRippleRejectBehavior.touchSlop

When TouchRippleRejectBehavior.leave

The Properties of TouchRippleOverlapBehavior

The enumeration defines the behavior of a touch ripple when it overlaps with other ripple effects.

Name	Description
overlappable	Sets the touch ripples to be allowed to overlap with each other.
cancel	Sets the touch ripple to be canceled if the effects overlap, with the new effect being added to the stack.
ignore	Sets the event to be ignored if the effects overlap, canceling the previous touch effect until it disappears.

When TouchRippleOverlapBehavior.overlappable

When TouchRippleOverlapBehavior.cancel

When TouchRippleOverlapBehavior.ignore

The Properties of TouchRippleCancelBehavior

The enumeration defines the behavior that defines the touch ripple spread animation when the touch ripple effect is canceled.

Name	Description
none	Sets the behavior to perform no action when the effect is canceled.
stop	Sets the behavior to stop the spread animation of the touch ripple effect when the effect is canceled.
reverse	Sets the behavior to reverse the spread animation of the touch ripple effect when the effect is canceled.

When TouchRippleCancelBehavior.none

When TouchRippleCancelBehavior.stop

When TouchRippleCancelBehavior.reverse

The Properties of TouchRippleFocusTiming

The enumeration defines when the focus of a touch ripple should start, specifying the priority based on timing conditions.

Name	Description
rejectable	Sets the focus event to start when the ripple is in a rejectable state, meaning the gesture has not yet been fully accepted, but the effect is visible and can be canceled.
consecutive	Sets the focus event to start when multiple ripple effects occur in rapid succession. This setting prevents the focus from being triggered prematurely when in a rejectable state.

When TouchRippleFocusTiming.rejectable

When TouchRippleFocusTiming.consecutive

The Properties of TouchRippleOrigin

The enumeration defines the starting point of a spread ripple effect, specifying the origin of the ripple based on the user interaction.

Name	Description
pointer_down	Sets the effect to originate from the point where the pointer-down.
pointer_move	Sets the effect to originate from the point where the pointer-move.
center	Sets the effect to originate from the center of the widget, regardless of the pointer's position.

When TouchRippleOrigin.pointer_down

When TouchRippleOrigin.pointer_move

When TouchRippleOrigin.center

The Properties of TouchRippleShape

The enumeration defines the shape of the ripple effect based on the widget layout, specifying how the ripple appears visually.

Name	Description
normal	Sets the shape to a square that corresponds to the area occupied by the widget layout.
inner_circle	Sets the shape to a circle that remains within the bounds of the widget layout.
outer_circle	Sets the shape to a circle that extends beyond the bounds of the widget layout.

When TouchRippleShape.normal

When TouchRippleShape.inner_circle

When TouchRippleShape.outer_circle

The Properties of TouchRippleRenderOrderType

The enumeration specifies the rendering order of the touch ripple effect, determining whether it should appear in the foreground or background.

Name	Description
foreground	Sets the behavior to draw the touch ripple in the foreground, meaning it will appear above all other visual widgets in the interface.
background	Sets the behavior to draw the touch ripple in the background, ensuring it appears beneath all other visual widgets in the interface.

When TouchRippleRenderOrderType.foreground

When TouchRippleRenderOrderType.background