Search packages, repositories and app categories

local_hero cover
Package detailsv0.3.0

local_hero

A widget which implicitly launches a hero animation when its position changed within the same route.

AndroidiOSWebmacOSWindowsLinux
30-day downloads
12.3K
Likes
274
Pub points
150

Install package

flutter pub add local_hero

Package Overview

Package selection guidance compiled from public package information, community data, and project usage.

The local_hero package enables implicit hero animations when a widget's position changes within the same route. It simplifies transitions by automatically animating the movement of a widget between its old and new positions, enhancing user experience with smooth visual flow. Ideal for navigation within a single screen or dynamic UI updates, it works across all major platforms including Android, iOS, Web, macOS, Windows, and Linux. The package is lightweight and integrates seamlessly with Flutter’s existing animation system.

Use cases

  • Smooth screen transitions within a single route
  • Animating widget repositioning during state changes
  • Enhancing UI feedback in dynamic lists
  • Creating intuitive navigation experiences
  • Supporting responsive layout shifts
  • Improving visual continuity in interactive apps

Key features

  • Automatic hero animation on position change
  • Seamless integration with Flutter’s animation system
  • Cross-platform support
  • Minimal boilerplate required
  • Works within the same route only
  • Complements existing Hero widgets

Suitable for

  • Developers building interactive UIs
  • Apps requiring fluid transitions
  • Teams prioritizing UX consistency
  • Projects using dynamic layouts
  • Flutter beginners learning animations
  • Apps with frequent widget repositioning

Considerations

  • Limited to same-route animations
  • Does not support cross-route transitions
  • Requires careful placement to avoid unexpected behavior
  • Not suitable for complex multi-screen navigation
  • May impact performance if overused
  • Best used with stable widget keys

Original README

Original README snapshot from the linked source repository. Visit the repository for the latest content.

local_hero

Pub

A widget which implicitly launches a hero animation when its position changed within the same route.

Overview

Getting started

In the pubspec.yaml of your flutter project, add the following dependency:

dependencies:
  ...
  local_hero:

In your library add the following import:

import 'package:local_hero/local_hero.dart';

Usage

To be animated implicitly, a widget needs to be surrounded by a LocalHero widget with a unique tag:

const LocalHero(
    tag: 'my_widget_tag',
    child: MyWidget(),
),

A LocalHero widget must have a LocalHeroScope ancestor which hosts the animations properties (duration, curve, etc.). At each frame we must have only one LocalHero per tag, per LocalHeroScope.

The following example shows the basic usage of a LocalHero widget:

class _LocalHeroPage extends StatelessWidget {
  const _LocalHeroPage({
    Key key,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: LocalHeroScope(
          duration: const Duration(milliseconds: 300),
          curve: Curves.easeInOut,
          child: const _LocalHeroPlayground(),
        ),
      ),
    );
  }
}

class _LocalHeroPlayground extends StatefulWidget {
  const _LocalHeroPlayground({
    Key key,
  }) : super(key: key);

  @override
  _LocalHeroPlaygroundState createState() => _LocalHeroPlaygroundState();
}

class _LocalHeroPlaygroundState extends State<_LocalHeroPlayground> {
  AlignmentGeometry alignment = Alignment.topLeft;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: <Widget>[
        Expanded(
          child: Padding(
            padding: const EdgeInsets.all(8),
            child: Align(
              alignment: alignment,
              child: const LocalHero(
                tag: 'id',
                child: _Box(),
              ),
            ),
          ),
        ),
        RaisedButton(
          onPressed: () {
            setState(() {
              alignment = alignment == Alignment.topLeft
                  ? Alignment.bottomRight
                  : Alignment.topLeft;
            });
          },
          child: const Text('Move'),
        ),
      ],
    );
  }
}

class _Box extends StatelessWidget {
  const _Box({
    Key key,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(
      color: Colors.red,
      width: 50,
      height: 50,
    );
  }
}

Example

Sponsoring

I'm working on my packages on my free-time, but I don't have as much time as I would. If this package or any other package I created is helping you, please consider to sponsor me so that I can take time to read the issues, fix bugs, merge pull requests and add features to these packages.

Changelog

Please see the Changelog page to know what's recently changed.

Contributions

Feel free to contribute to this project.

If you find a bug or want a feature, but don't know how to fix/implement it, please fill an issue.
If you fixed a bug or implemented a feature, please send a pull request.

Categories

Dependencies

Dependency list 1 items

Source repository

Projects using this package