⚠️ This package is in an early state of development. If you find any bugs or have any suggestions, please open an issue.
Fleet is an animation framework for Flutter.
- State-based: Animate transitions from one state to another.
- Declarative: Describe an animation and apply it to a state change. No need to manage
AnimationController
s orTween
s. - Animatable widgets: Comes out of the box with general purpose widgets that support animating with Fleet.
- Extensible: Any widget can be made to support animating with Fleet.
- Flexible: Animatable widgets can be used with or without animations.
- Composable: Widgets that build on animatable widgets are automatically animatable.
- Animate parameters individually: Animate parameters of animatable widget individually, e.g. with different curves.
- User-friendly: Add and change animations with little refactoring.
Getting started
- Add Fleet to your
pubspec.yaml
:
flutter pub add fleet
- Add
FleetBinding.ensureInitialized()
to yourmain
function:
import 'package:fleet/fleet.dart';
import 'package:flutter/material.dart';
void main() {
FleetBinding.ensureInitialized();
runApp(MyApp());
}
You need to use this binding instead of WidgetsFlutterBinding
.
This step is currently necessary because of functionality that Fleet requires, but that is not available in Flutter. This step will become unnecessary if and when the required functionality becomes available in Flutter. Unfortunately, this also means that until that point, animations that use Fleet will not work in tests. The reason is that the test bindings cannot be extended in the same way that WidgetsFlutterBinding
can be. You can still use Fleet in tests but animated values will immediately jump to their final value.
Now you're ready to use Fleet in your Flutter app.
Take a look a the examples or continue to the introduction to Fleet.
Introduction
Fleet has been heavily inspired by the animation framework that comes with SwiftUI. If you are familiar with it, you will find most concepts familiar.
I'm going to walk you through adding a simple animation to a widget. Below is the unanimated version of the widget:
import 'package:fleet/fleet.dart';
import 'package:flutter/material.dart';
class MyWidget extends StatefulWidget {
const MyWidget({super.key});
@override
State<MyWidget> createState() => _MyWidgetState();
}
class _MyWidgetState extends State<MyWidget> {
var _active = false;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: () {
setState(() {
_active = !_active;
});
},
child: ColoredBox(
color: _active ? Colors.blue : Colors.grey,
),
);
}
}
Now lets animate the state change of _active
:
-class _MyWidgetState extends State<MyWidget> {
+class _MyWidgetState extends State<MyWidget> with AnimatingStateMixin {
var _active = false;
@override
Widget build(BuildContext context) {
return GestureDetector(
onTap: () {
- setState(() {
+ setStateAsync(animation: Curves.ease.animation(250.ms), () {
_active = !_active;
});
},
- child: ColoredBox(
+ child: AColoredBox(
color: _active ? Colors.blue : Colors.grey,
),
);
}
}
We made the following changes:
- Mixin
AnimatingStateMixin
to_MyWidgetState
, so we can usesetStateAsync
. - Use
setStateAsync
to specify the animation that we want to apply to the state change. - Use
AColoredBox
instead ofColoredBox
.
The AColoredBox
widget is a drop-in replacement for ColoredBox
that supports animating with Fleet. Widgets that support animating with Fleet don't have any special parameters related to animation and can be used without animation, just as well.
Fleet provides drop-in replacements for a number of generally useful Flutter framework widgets (all with the prefix A
). Any widget can be made to support state-based animation through components provided by Fleet (see AnimatableStateMixin
). Issues or PRs for adding support for more widgets are welcome!
Note that we did not explicitly tell setStateAsync
what to animate. This is because Fleet uses a state-based approach. All state changes caused by executing the provided callback will be animated. Even the state changes which are indirect, like the color
parameter of AColoredBox
going from Colors.grey
to Colors.blue
. Fleet does this by tracking the state of animatable parameters of animatable widgets from one build to the next.
setStateAsync
is a little bit special in that it does not immediately execute the callback, like it is the case for setState
. Instead, setStateAsync
executes the callback as part of building the next frame.
Curves.ease.animation(250.ms)
creates an AnimationSpec
that we pass to setStateAsync
to specify how to animate from the old to the new state.
.animate
is an extension method on Curve
that creates an AnimationSpec
form the curve. It optionally takes a Duration
. For a nicer syntax for specifying Duration
s, Fleet provides extensions on int
, e.g 250.ms
is equivalent to Duration(milliseconds: 250)
.
Animatable widgets
The following drop-in replacements for Flutter framework widgets are provided for animating with Fleet:
- AAlign
- AColoredBox
- AContainer
- AOpacity
- APadding
- APositioned
- APositionedDirectional
- ASizedBox
- ASliverOpacity
- ASliverPadding
- ATransform
Gabriel Terwesten • GitHub @blaugold • Twitter @GTerwesten • Medium @gabriel.terwesten