drag_wave_slider 0.2.0

A customizable drag slider with beautiful wave animation effect for Flutter apps. Perfect for slide-to-action interactions with animated wave trails.

Drag Wave Slider

A beautiful and customizable drag slider widget with animated wave trail effect for Flutter applications. Perfect for slide-to-action interactions like "slide to unlock", "slide to confirm", or any action that requires deliberate user input.

Features

• Animated Wave Trail: Beautiful wave animation that follows the slider thumb
• Completion Animation: The thumb glides to the end and morphs into a checkmark on success
• Drag Anywhere: Start a drag anywhere on the track, not just on the thumb
• Live Progress Callback: React in real-time to drag position via onSlideChange
• Animated Snap Back: Releasing early springs the thumb home with a configurable duration and curve
• Custom Text Style: Full TextStyle control over the label via textStyle
• Reset Control: Choose whether the thumb snaps back or stays at the end after completion
• Enable / Disable: Fully disable interaction with a greyed-out visual state
• Custom Thumb Widget: Use any Flutter widget as the slider thumb
• Custom Label Widget: Use any Flutter widget as the slider label
• Thumb Gradient: Apply a gradient fill to the thumb instead of a flat color
• RTL Support: Works seamlessly with right-to-left layouts
• Smooth Performance: Wave path uses Bézier curves instead of per-pixel rendering
• Zero Dependencies: Only depends on Flutter SDK

Screenshots

LTR (Left-to-Right)

RTL (Right-to-Left)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  drag_wave_slider: ^0.2.0

Usage

import 'package:drag_wave_slider/drag_wave_slider.dart';

Basic

DragWaveSlider(
  text: 'Slide to Unlock',
  sliderColor: Colors.blue,
  backgroundColor: Colors.grey,
  textColor: Colors.white,
  onSlideComplete: () {
    print('Unlocked!');
  },
)

Live progress with onSlideChange

DragWaveSlider(
  text: 'Drag me',
  sliderColor: Colors.orange,
  onSlideComplete: () {},
  onSlideChange: (double value) {
    // value is 0.0 – 1.0
    print('Progress: ${(value * 100).toStringAsFixed(1)}%');
  },
)

Keep thumb at end (resetOnComplete: false)

DragWaveSlider(
  text: 'Slide to Confirm',
  sliderColor: Colors.green,
  resetOnComplete: false,
  onSlideComplete: () {
    // thumb stays at the end position
  },
)

Completion animation

On completion the thumb glides to the end of the track and its icon morphs into completionIcon. Turn it off with animateCompletion: false.

DragWaveSlider(
  text: 'Slide to Archive',
  sliderColor: Colors.amber,
  thumbIcon: Icons.archive_outlined,
  completionIcon: Icons.done_all,
  completionDuration: const Duration(milliseconds: 250),
  completionHoldDuration: const Duration(seconds: 1),
  onSlideComplete: () {},
)

// Instant completion — no glide, no checkmark
DragWaveSlider(
  text: 'Instant',
  animateCompletion: false,
  onSlideComplete: () {},
)

The icon morph is skipped when you supply a custom thumbWidget, since the package cannot know how to restyle your widget.

Custom text style

textStyle is merged over the built-in defaults, so you only set what you want to change. A color here takes priority over textColor.

DragWaveSlider(
  text: 'SLIDE TO SEND',
  textStyle: TextStyle(
    color: Colors.blueGrey.shade900,
    fontSize: 12,
    fontWeight: FontWeight.w800,
    letterSpacing: 4,
  ),
  onSlideComplete: () {},
)

Drag anywhere on the track

By default a drag may start anywhere on the track — the thumb follows the horizontal movement of your finger. Set dragAnywhere: false to require the gesture to start on the thumb itself.

DragWaveSlider(
  text: 'Grab the Thumb',
  dragAnywhere: false,
  onSlideComplete: () {},
)

Snap back animation

Releasing before the threshold animates the thumb back to the start.

DragWaveSlider(
  text: 'Let Go Half Way',
  resetDuration: const Duration(milliseconds: 900),
  resetCurve: Curves.elasticOut,
  onSlideComplete: () {},
)

// Or snap back instantly
DragWaveSlider(
  text: 'No Animation',
  resetDuration: Duration.zero,
  onSlideComplete: () {},
)

Disabled state

DragWaveSlider(
  text: 'Unavailable',
  enabled: false,
  onSlideComplete: () {},
)

Thumb gradient

DragWaveSlider(
  text: 'Slide to Pay',
  sliderColor: Colors.teal,
  thumbIcon: Icons.payment,
  thumbGradient: LinearGradient(
    colors: [Colors.teal, Colors.cyan],
    begin: Alignment.topLeft,
    end: Alignment.bottomRight,
  ),
  onSlideComplete: () {},
)

Custom thumb widget

DragWaveSlider(
  text: 'Custom Thumb',
  sliderColor: Colors.deepPurple,
  thumbWidget: Container(
    decoration: BoxDecoration(
      shape: BoxShape.circle,
      gradient: LinearGradient(
        colors: [Colors.deepPurple, Colors.pink],
      ),
    ),
    child: Icon(Icons.star, color: Colors.white),
  ),
  onSlideComplete: () {},
)

Custom label widget

DragWaveSlider(
  textWidget: Row(
    mainAxisSize: MainAxisSize.min,
    children: [
      Icon(Icons.lock_open, size: 16, color: Colors.green),
      SizedBox(width: 6),
      Text('SLIDE TO UNLOCK',
          style: TextStyle(color: Colors.green, letterSpacing: 1.5)),
    ],
  ),
  sliderColor: Colors.green,
  onSlideComplete: () {},
)

RTL support

Directionality(
  textDirection: TextDirection.rtl,
  child: DragWaveSlider(
    text: 'اسحب للفتح',
    sliderColor: Colors.purple,
    onSlideComplete: () {},
  ),
)

Parameters

Parameter	Type	Default	Description
text	String?	—	Text label (required if textWidget is not set)
textWidget	Widget?	null	Custom widget label (overrides text)
textStyle	TextStyle?	null	Style merged over the default label style
onSlideComplete	VoidCallback	required	Fires once per completed slide, when the threshold is reached
onSlideChange	ValueChanged<double>?	null	Fires continuously with drag progress (0.0–1.0)
resetOnComplete	bool	true	Whether the thumb resets to start after completion
enabled	bool	true	Whether the slider accepts user interaction
sliderColor	Color	Colors.blue	Color of slider thumb and wave trail
thumbGradient	Gradient?	null	Gradient fill for the thumb (overrides sliderColor on thumb)
thumbWidget	Widget?	null	Fully custom thumb widget (overrides thumbIcon)
thumbIcon	IconData?	null	Icon displayed inside the thumb
thumbIconColor	Color?	null	Color of the thumb icon
backgroundColor	Color	Colors.grey	Background color of the slider track
textColor	Color	Colors.white	Color of the text label
height	double	60	Height of the slider
waveAmplitude	double	3.0	Amplitude of the wave animation
waveDuration	Duration	1500ms	Duration of one wave animation cycle
slideThreshold	double	0.9	Drag fraction that triggers onSlideComplete. Must be > 0.0 and <= 1.0
dragAnywhere	bool	true	Whether a drag may start anywhere on the track, not just on the thumb
animateCompletion	bool	true	Whether to glide the thumb to the end and morph its icon on completion
completionDuration	Duration	250ms	Duration of the completion glide
completionHoldDuration	Duration	600ms	How long the completion icon stays before resetting
completionIcon	IconData	Icons.check	Icon the thumb morphs into on completion
resetDuration	Duration	300ms	Duration of the snap back to start (Duration.zero for instant)
resetCurve	Curve	Curves.easeOut	Curve of the snap back to start

Example

See the /example directory for a complete demo app showcasing all configurations.

License

MIT License - see LICENSE file for details.