collection_animated 0.0.8

Collection Animated flutter package

collection_animated

A Flutter package for smooth "add to cart" style fly animations. An item launches from any widget and flies in an arc to a target widget (cart, favorites, etc).

Features

• Launch angle — control the exact direction the item flies out (0–360°)
• Back offset — how far the item travels before heading to the target
• Side offset — lateral drift during the launch phase
• Arc height — how high the item arcs on its way to the target
• Launch duration — control the speed of the initial launch phase
• Fly duration — control the speed of the flight phase to the target
• Scale animation — optional shrink effect during flight
• Scale range (launch) — customize start and end scale during the launch phase
• Scale range (fly) — customize start and end scale during the fly phase
• Opacity animation — optional opacity effect during flight
• Opacity range (launch) — customize start and end opacity during the launch phase
• Opacity range (fly) — customize start and end opacity during the fly phase
• Top shift — vertical offset applied to the flying widget's position on the overlay
• Left shift — horizontal offset applied to the flying widget's position on the overlay
• onCompleted callback — get notified when the animation finishes
• GlobalKey-based — no widget wrapping needed, just attach keys

Getting started

Your State must use TickerProviderStateMixin:

class _MyPageState extends State<MyPage> with TickerProviderStateMixin {

Usage

1. Create keys for the button and target:

final GlobalKey cartKey   = GlobalKey();
final GlobalKey buttonKey = GlobalKey();

2. Attach keys to your widgets:

// Target (e.g. cart icon in AppBar)
Icon(Icons.shopping_cart, key: cartKey)

// Button (e.g. "Add" button)
ElevatedButton(key: buttonKey, ...)

3. Create a CollectionAnimated instance:

late final CollectionAnimated _anim;

@override
void initState() {
  super.initState();
  _anim = CollectionAnimated(
    vsync: this,
    buttonKey: buttonKey,
    targetKey: cartKey,
    flyWidget: const Icon(Icons.favorite, color: Colors.red, size: 40),
  );
}

4. Call startAnimation() on tap:

onPressed: () => _anim.startAnimation(),

Full example

class _MyPageState extends State<MyPage> with TickerProviderStateMixin {
  final GlobalKey cartKey   = GlobalKey();
  final GlobalKey buttonKey = GlobalKey();

  late final CollectionAnimated _anim;

  @override
  void initState() {
    super.initState();
    _anim = CollectionAnimated(
      vsync: this,
      buttonKey: buttonKey,
      targetKey: cartKey,
      flyWidget: const Icon(Icons.favorite, color: Colors.red, size: 40),
      launchAngle: 270,   // fly upward
      backOffset: 80,     // travel 80px in launch direction
      sideOffset: 60,     // drift 60px sideways
      arcHeight: 180,     // arc height during flight
      scaleAnimated: true,
      onCompleted: () => print('Animation done!'),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        actions: [
          Padding(
            padding: const EdgeInsets.all(12),
            child: Icon(Icons.shopping_cart, key: cartKey, size: 32),
          ),
        ],
      ),
      body: Center(
        child: ElevatedButton(
          key: buttonKey,
          onPressed: () => _anim.startAnimation(),
          child: const Text('Add to cart'),
        ),
      ),
    );
  }
}

Parameters

Parameter	Type	Default	Description
vsync	TickerProvider	required	Pass this from your State
buttonKey	GlobalKey	required	Key on the source widget
targetKey	GlobalKey	required	Key on the destination widget
flyWidget	Widget	required	The widget that flies
launchAngle	double	270	Launch direction in degrees (0=right, 90=down, 180=left, 270=up)
backOffset	double	80	Distance traveled in launch direction before flying to target
sideOffset	double	60	Lateral drift perpendicular to launch direction
arcHeight	double	180	Height of the arc during flight to target
launchDuration	Duration	350ms	Duration of the launch phase
flyDuration	Duration	600ms	Duration of the flight phase
scaleAnimated	bool	false	Whether the item shrinks during flight
opacityAnimated	bool	false	Changes transparency during the flight
opacityPhase1	CollectionAnimatedValues	begin: 0.1, end: 1.0	Opacity range during the launch phase
opacityPhase2	CollectionAnimatedValues	begin: 1.0, end: 0.3	Opacity range during the fly phase
scalePhase1	CollectionAnimatedValues	begin: 0.1, end: 1.0	Scale range during the launch phase
scalePhase2	CollectionAnimatedValues	begin: 1.0, end: 0.5	Scale range during the fly phase
topShift	double	20	Vertical offset for the flying widget's overlay position
leftShift	double	20	Horizontal offset for the flying widget's overlay position
onCompleted	VoidCallback?	null	Called when the animation completes

Additional information

• Issues & feature requests — open an issue on GitHub
• Contributions — PRs are welcome! Please open an issue first to discuss what you'd like to change
• License — MIT