HeroContainer class

A widget that provides smooth animated transitions between a closed and opened state using widget snapshots.

HeroContainer creates seamless animated transitions between two states: a closed state that displays a compact widget, and an opened state that displays a full-screen or expanded widget. Unlike traditional hero animations, this widget captures snapshots (images) of both the closed and opened widgets, then animates between these snapshots for consistently smooth performance regardless of widget complexity.

The widget takes two builders:

closedBuilder: Builds the widget shown in the closed state
openedBuilder: Builds the widget shown in the opened state

When the action callback from closedBuilder is invoked, the container will capture snapshots of both widgets and animate between them.

How it works

Snapshot Capture: Both widgets are rendered and captured as images
Smooth Animation: The transition animates between these snapshots
Performance: Complex widgets animate smoothly since only images are animated
Visual Continuity: Maintains perfect visual fidelity during transitions

Performance Benefits

Unlike traditional widget-based animations that can stutter with complex layouts, HeroContainer maintains smooth 120fps performance by animating pre-captured images instead of live widgets.

Example

HeroContainer(
  closedBuilder: (context, action) {
    return TextButton(
      onPressed: action,
      child: Text("Tap to expand", style: TextStyle(fontSize: 50))
    );
  }
  openedBuilder: (context) {
    return Scaffold(
      appBar: AppBar(title: Text("Expanded View")),
      body: Center(
        child: Text("Hello, World!", style: TextStyle(fontSize: 32)),
      ),
    );
  },
)

Inheritance

Constructors

HeroContainer({Key? key, Color? openedColor, Color? closedColor, ShapeBorder? openedShape, ShapeBorder? closedShape, HeroContianerClosedCallback? onClosed, double openedElevation = 4.0, double closedElevation = 1.0, BoxFit openedFit = BoxFit.fitWidth, BoxFit closedFit = BoxFit.fitWidth, AlignmentGeometry closedAlignment = Alignment.topCenter, AlignmentGeometry openedAlignemnt = Alignment.topCenter, Duration transitionDuration = const Duration(milliseconds: 300), Curve transitionCurve = Curves.fastOutSlowIn, HeroContianerFlightShuttleBuilder? flightShuttleBuilder, required WidgetBuilder openedBuilder, required HeroContainerBuilder closedBuilder}): Creates a hero container with customizable transition properties.
const

Properties

closedAlignment → AlignmentGeometry: How to align the image within its bounds during the closed state.
final
closedBuilder → HeroContainerBuilder: Builder for the widget displayed in the closed/collapsed state.
final
closedColor → Color?: The background color of the container in the closed state. If null, defaults to the theme's surface color.
final
closedElevation → double: The elevation of the container in the closed state.
final
closedFit → BoxFit: How the image should be inscribed into the space allocated during the closed state of the transition.
final
closedShape → ShapeBorder?: The shape of the container in the closed state. If null, the container will have no specific shape.
final
flightShuttleBuilder → HeroContianerFlightShuttleBuilder?: A custom builder for the widget shown during the snapshot transition.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
onClosed → HeroContianerClosedCallback?: Called when the container transitions from opened back to closed state.
final
openedAlignemnt → AlignmentGeometry: How to align the image within its bounds during the opened state.
final
openedBuilder → WidgetBuilder: Builder for the widget displayed in the opened/expanded state.
final
openedColor → Color?: The background color of the container in the opened state. If null, defaults to the theme's surface color.
final
openedElevation → double: The elevation of the container in the opened state.
final
openedFit → BoxFit: How the image should be inscribed into the space allocated during the opened state of the transition.
final
openedShape → ShapeBorder?: The shape of the container in the opened state. If null, the container will have no specific shape.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
transitionCurve → Curve: The curve used for the transition animation.
final
transitionDuration → Duration: The duration of the transition animation.
final

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<HeroContainer>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited