Flutter Spring Animation #

A Flutter package for creating smooth spring-based animations with customizable damping, stiffness, and velocity parameters. Perfect for creating natural, physics-based UI transitions.

Features #

• 🌸 Natural Spring Physics: Realistic spring animations based on physics principles
• ⚙️ Highly Customizable: Adjust damping, stiffness, mass, and velocity parameters
• 🎯 Easy to Use: Simple API with both imperative and declarative approaches
• 🚀 Performance Optimized: Efficient animations that run at 60fps
• 📱 Flutter Compatible: Works with Flutter 3.10.0+
• 🎨 Rich Widget Set: Pre-built transition widgets for common use cases
• 🧪 Well Tested: Comprehensive test coverage
• 📚 Fully Documented: Complete API documentation and examples

Installation #

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

dependencies:
  flutter_spring_animation: ^0.0.1

Then run:

$ flutter pub get

Quick Start #

Basic Usage #

import 'package:flutter_spring_animation/flutter_spring_animation.dart';

// Create a spring animation
final springAnimation = SpringAnimation(
  config: SpringConfig.bouncy,
  from: 0.0,
  to: 1.0,
);

// Start the animation
springAnimation.start(
  onUpdate: (value) {
    print('Current value: $value');
  },
  onComplete: () {
    print('Animation completed!');
  },
);

Using SpringController #

class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late SpringController _controller;

  @override
  void initState() {
    super.initState();
    _controller = SpringController(
      config: SpringConfig.gentle,
      initialValue: 0.0,
    );
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _controller,
      builder: (context, child) {
        return Transform.scale(
          scale: 0.5 + (_controller.value * 0.5),
          child: Container(
            width: 100,
            height: 100,
            color: Colors.blue,
          ),
        );
      },
    );
  }

  void _animate() {
    _controller.animateTo(1.0);
  }
}

Declarative Approach with SpringAnimationBuilder #

SpringAnimationBuilder(
  config: SpringConfig.wobbly,
  target: isVisible ? 1.0 : 0.0,
  builder: (context, value) {
    return Opacity(
      opacity: value,
      child: Transform.scale(
        scale: value,
        child: Container(
          width: 100,
          height: 100,
          color: Colors.red,
        ),
      ),
    );
  },
)

Spring Configurations #

The package includes several pre-configured spring settings:

// Bouncy spring with some oscillation
SpringConfig.bouncy

// Gentle spring with smooth motion
SpringConfig.gentle

// Wobbly spring with more oscillation
SpringConfig.wobbly

// Stiff spring with quick motion
SpringConfig.stiff

// Slow spring with extended duration
SpringConfig.slow

// Custom configuration
SpringConfig(
  damping: 26.0,
  stiffness: 160.0,
  mass: 1.0,
  velocity: 0.0,
  tolerance: 0.01,
)

Pre-built Transition Widgets #

SpringTransition #

A general-purpose transition widget that combines opacity and scale animations:

SpringTransition(
  visible: isVisible,
  config: SpringConfig.bouncy,
  child: Container(
    width: 100,
    height: 100,
    color: Colors.green,
  ),
)

SpringSlideTransition #

Slides widgets in from different directions:

SpringSlideTransition(
  visible: isVisible,
  direction: AxisDirection.up,
  config: SpringConfig.gentle,
  child: Text('Hello World!'),
)

SpringRotationTransition #

Rotates widgets with spring physics:

SpringRotationTransition(
  visible: isVisible,
  turns: 0.25, // 90 degrees
  config: SpringConfig.wobbly,
  child: Icon(Icons.star),
)

SpringSizeTransition #

Animates widget size with spring motion:

SpringSizeTransition(
  visible: isVisible,
  axis: Axis.horizontal, // or Axis.vertical, or null for both
  config: SpringConfig.stiff,
  child: Text('Expanding text'),
)

Advanced Usage #

Custom Spring Physics #

Understanding the spring parameters:

• Damping: Controls oscillation (higher = less bouncy)
• Stiffness: Controls animation speed (higher = faster)
• Mass: Controls inertia (higher = slower)
• Velocity: Initial velocity of the animation
• Tolerance: Threshold for animation completion

final customConfig = SpringConfig(
  damping: 15.0,    // Low damping for more bounce
  stiffness: 200.0, // High stiffness for quick response
  mass: 0.8,        // Light mass for snappy motion
  velocity: 5.0,    // Start with some initial velocity
);

Chaining Animations #

void chainAnimations() async {
  await _controller.animateTo(1.0);
  await _controller.animateTo(0.5);
  await _controller.animateTo(0.0);
}

Toggle Animation #

final toggleController = SpringController.toggle(
  config: SpringConfig.bouncy,
  initialValue: false,
);

// Toggle between states
toggleController.toggleValue();

Bounce Animation #

final bounceController = SpringController.bounce(
  config: SpringConfig.wobbly,
  min: 0.0,
  max: 1.0,
  duration: Duration(seconds: 1),
);

Performance Tips #

1. Dispose controllers: Always dispose SpringController instances in your widget's dispose method
2. Reuse configurations: Create SpringConfig instances once and reuse them
3. Use tolerance: Adjust tolerance values for your use case to avoid unnecessary calculations
4. Avoid excessive updates: Don't create new animations too frequently

Examples #

Check out the example directory for a complete sample app demonstrating various use cases:

• Basic spring animations
• Interactive toggles
• List item animations
• Page transitions
• Custom physics demonstrations

To run the example:

cd example
flutter run

API Reference #

SpringConfig #

Configuration class for spring animation parameters.

Properties:

• damping (double): Damping coefficient (default: 26.0)
• stiffness (double): Spring stiffness (default: 160.0)
• mass (double): Mass of animated object (default: 1.0)
• velocity (double): Initial velocity (default: 0.0)
• tolerance (double): Completion tolerance (default: 0.01)

Methods:

• copyWith(): Create a copy with modified parameters
• Static presets: bouncy, gentle, wobbly, stiff, slow

SpringAnimation #

Core animation class implementing spring physics.

Properties:

• value (double): Current animation value
• velocity (double): Current velocity
• isRunning (bool): Whether animation is active
• isCompleted (bool): Whether animation has finished

Methods:

• start(): Begin animation with callbacks
• stop(): Stop current animation
• reset(): Reset to initial state
• updateTarget(): Change target during animation

SpringController #

ChangeNotifier-based controller for widget integration.

Properties:

• value (double): Current animation value
• target (double): Target value
• isAnimating (bool): Whether actively animating
• velocity (double): Current velocity

Methods:

• animateTo(): Animate to target value
• setValue(): Set value immediately
• forward(): Animate to 1.0
• reverse(): Animate to 0.0
• toggleValue(): Toggle between 0.0 and 1.0

SpringAnimationBuilder #

Widget builder for declarative animations.

Parameters:

• config (SpringConfig): Animation configuration
• target (double): Target value to animate to
• builder (Function): Widget builder function
• initialValue (double): Starting value (default: 0.0)

Physics Background #

This package implements a damped harmonic oscillator using the equation:

F = -kx - cv

Where:

• F is the force
• k is the spring constant (stiffness)
• x is the displacement from target
• c is the damping coefficient
• v is the velocity

The integration uses an improved Euler method for stability and performance.

Contributing #

Contributions are welcome! Please read our contributing guidelines and code of conduct.

Development Setup #

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run tests: flutter test
6. Submit a pull request

License #

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Changelog #

See CHANGELOG.md for version history and changes.

Support #

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Related Packages #

• animations - Material motion animations
• flutter_sequence_animation - Sequence animations
• simple_animations - Simple animation utilities

Made with ❤️ for the Flutter community