Physics-first Flutter animations with a composable, timeline-driven API for building polished transitions, expressive UI motion, and reusable animation systems without wiring imperative controllers through your widget tree.
If you are exploring animations during development, enable CueDebugTools right after you get the basic setup working. It gives you a scrubber for completed Cue animations and is best wrapped in a kDebugMode check:
Cue publishes a CueController to its subtree through CueScope. Any Actor below it can use it to build animations.
Use the factory that matches the trigger you want:
Direction matters here:
Cue.onMount plays forward when the widget is inserted into the tree. It is a one-way entrance trigger unless you opt into repeat behavior.
Cue.onToggle plays forward when toggled becomes true, and plays in reverse when toggled becomes false.
Cue.onChange restarts from 0 and plays forward each time the tracked value changes. It does not reverse based on the old and new values.
Cue.onHover plays forward on pointer enter, and reverses on pointer exit.
Cue.onFocus plays forward when the widget gains focus, and reverses when it loses focus.
Cue.onScroll is scrubbed by scroll position. It does not simply fire forward or reverse once; progress is continuously mapped to where the widget is in the viewport.
Cue.onScrollVisible maps visibility to animation progress. It moves forward as the widget enters the viewport and reverses as the widget exits it.
Cue.onProgress is scrubbed by an external progress source. The listenable drives the current value directly, so direction depends on whether the external progress is increasing or decreasing.
Cue.indexed is driven by an indexed controller. Items ahead of the active offset move forward, while items behind it move in reverse as the controller moves between indices.
Cue(...) gives you full imperative control. You decide the direction by calling methods such as forward, reverse, animateTo, or by setting progress directly on your controller.
In sliver layouts (for example CustomScrollView), animate the non-sliver widget you render inside each sliver (such as a SliverToBoxAdapter child or SliverList item). For SliverAppBar headers, use CueFlexibleSpaceBar.
Actor is the visual building block. It takes a child plus one or more acts and applies them using the nearest Cue.
Important rules:
Actor is passive. Without an ancestor Cue, it will throw.
One Actor can apply multiple acts at once.
Acts eventually resolve into nested widget wrappers around the child, so ordering matters. For example, clipping before transforming is not always the same as transforming before clipping.
Only one act per act key is allowed in the same Actor. For example, two slide variants in one Actor are not allowed because they share the same key.
motion on an act overrides Actor.motion, which overrides the parent Cue motion.
You can also attach acts inline with the widget extension:
Cue.indexed is commonly used with CuePageController, where each page gets its own indexed cue and can animate multiple children as the page moves in and out.
Use the trigger factories first. Reach for controllers when you need explicit orchestration.
CueController is an AnimationController backed by a CueTimeline. It keeps Cue's motion and track system available even when you are driving animation manually.
Important differences from a normal AnimationController:
Duration is derived from the timeline motion. You do not set duration or reverseDuration directly.
The timeline manages tracks, and each track can have its own motion.
To remove a track from the timeline, every obtainer of that track must release it.
If you rebuild the timeline with a new default motion, previously obtained tracks become stale and must be obtained again.
Available controller types include:
CueController for direct control.
CuePageController and CueTabController for navigation-driven progress.
CueIndexController and IndexedCueController for sequences and staggered lists.
SelfAnimatedCue for self-contained animation ownership.
When working manually with CueController, there are two levels of API:
High-level: pass the controller into Cue(controller: ...) and let Actors consume it through CueScope.
Low-level: obtain tracks with obtainTrack, tweenTrack, or keyframedTrack when you need typed imperative animations outside the normal widget helpers.
If the controller itself is being disposed, you do not need to release those tracks manually. Disposing the controller disposes the timeline and everything attached to it.
If the controller stays alive but a specific imperative animation is no longer needed, release that animation so its underlying track can be removed when no other obtainers still hold it.
Track lifecycle matters here:
obtainTrack returns a track plus a ReleaseToken.
tweenTrack and keyframedTrack wrap that same mechanism and expose CueAnimation.release().
A track is only removed after every token for it has been released.
If you call rebuildTimeline(...) because the default motion changed, all previously obtained tracks become stale, including tracks that had their own motion override. Re-obtain them after rebuilding.
Cue widgets handle all of this automatically. These details only matter when you use the controller as a low-level imperative API.
Higher-Level Helpers
Cue also includes higher-level widgets for common transition patterns.
showCueDialog and CueDialogRoute
Use Cue-powered route transitions for dialogs and overlays. Actors inside the route automatically pick up the route controller through CueScope.
Use this when a trigger should expand into contextual modal content. The builder receives the trigger rectangle, so it is easy to animate size and position from the original source.
scrubForwardDirection (required) defines which drag direction maps to forward progress. Use CueScrubAxis.start/.end for logical directions that adapt to text direction (LTR/RTL), or .left/.right/.up/.down for absolute physical directions.
distance must be positive. To reverse the drag direction, use the opposite CueScrubAxis instead of a negative distance.
CueFlexibleSpaceBar
A drop-in replacement for Flutter's FlexibleSpaceBar that provides cue animations driver through context, the animations are driven by the collapse progress of the flexible space bar.
CueFlexibleSpaceBar(
background: Center(child:
Actor(
acts: [.fadeIn(), .zomeIn()],
child: Image.asset('header.jpg'),
),
),
title: constText('Title'), // can animate anyting here as well
)
Does not react to SliverAppBar.expandedHeight changes at runtime. Use a ValueKey if you have dynamic heights.
Custom Animations
When the built-in acts are not enough, there are two main paths:
Build your own Act when you want a reusable effect that fits naturally into normal Actor(acts: [...]) composition.
Use TweenActor<T> when you want to animate a custom value and render it directly with a builder.
TweenActor is the simplest custom entry point. You provide from, to, and a builder, and Cue gives you an animation you can use to drive any widget tree:
Cue also ships composed actor helpers for common cases where the act and widget shape already belong together:
PositionedActor for animating Position inside a Stack
DecoratedBoxActor for animated box decoration
CardActor for animated card properties
PaintActor for painting with animation progress
Use those when they match the job, and build your own Act or TweenActor when they do not.
Recommended Style
Cue works best when call sites stay terse.
Prefer Cue.onToggle(motion: .smooth(), ...) over verbose class-qualified constructors when type inference is clear.
Prefer .fadeIn(), .slideY(), .scale() and other shorthand act factories in act lists.
Prefer Cue.acts or widget.act([...]) for single-child cases.
Use an explicit Actor when you need multiple animated descendants with different delays or motions.
Put one Cue high enough in the tree to coordinate related actors.
In short: use the shorthand named constructors whenever possible. That is the cleanest API Cue offers.
AI Agent Skills
Cue ships animation skills that give AI coding agents deep knowledge of the Cue API for accurate code generation, act suggestions, and motion guidance.
Quick Install (Recommended)
Install the skills package and get the cue animation skill:
skills get cue
Manual Installation
Copy the skill from the Cue/skills folder into your project's AI agent skills directory:
GitHub Copilot: Copy to .github/skills/cue-animations/SKILL.md
Kilo: Copy to .kilo/skill/cue-animations.md
Other agents: Check your agent's documentation for the correct skills path