How to Use the lottie Flutter Package for Rich Animations

Introduction

The lottie Flutter package lets you render After Effects animations exported as JSON files directly in Flutter. It removes the need to hand‑code complex motion graphics while keeping the bundle size low.

When to Use the lottie Flutter Package

Consider Lottie when you need:

• High‑quality vector animations that scale on any screen density.
• Quick iteration – designers can update the JSON without touching Dart code.
• Consistent animation performance across iOS, Android, and web.

If your animation is purely decorative and you already have a custom solution, weigh the added dependency against the benefits.

Installation

Add the package with the Flutter CLI:

flutter pub add lottie

After the command finishes, run flutter pub get to fetch the latest version.

Basic Usage

Below is a minimal, runnable example that shows how to display a local Lottie file and a remote animation.

import 'package:flutter/material.dart';
import 'package:lottie/lottie.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Lottie Demo',
      home: const Scaffold(
        appBar: AppBar(title: Text('Lottie in Flutter')),
        body: LottieDemo(),
      ),
    );
  }
}

class LottieDemo extends StatelessWidget {
  const LottieDemo({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      children: [
        // Local asset animation
        Lottie.asset(
          'assets/animations/hello.json',
          width: 200,
          height: 200,
          repeat: true,
        ),
        const SizedBox(height: 30),
        // Remote animation from a URL
        Lottie.network(
          'https://assets10.lottiefiles.com/packages/lf20_jcikwtux.json',
          width: 200,
          height: 200,
          repeat: false,
        ),
      ],
    );
  }
}

Make sure the JSON file is listed under assets in pubspec.yaml:

flutter:
  assets:
    - assets/animations/hello.json

Controlling Playback

If you need fine‑grained control (play, pause, seek), create a LottieBuilder with a controller.

class ControlledLottie extends StatefulWidget {
  const ControlledLottie({Key? key}) : super(key: key);

  @override
  State<ControlledLottie> createState() => _ControlledLottieState();
}

class _ControlledLottieState extends State<ControlledLottie> with SingleTickerProviderStateMixin {
  late final AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(vsync: this);
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Lottie.asset(
          'assets/animations/loop.json',
          controller: _controller,
          onLoaded: (composition) {
            // Set the controller's duration to the animation's length.
            _controller.duration = composition.duration;
            _controller.repeat(); // or .forward() for one‑shot.
          },
        ),
        ElevatedButton(
          onPressed: () {
            if (_controller.isAnimating) {
              _controller.stop();
            } else {
              _controller.forward();
            }
          },
          child: const Text('Play / Pause'),
        ),
      ],
    );
  }
}

Setup Notes & Common Mistakes

• Asset path errors: The JSON file must be declared in pubspec.yaml and the path must be exact (case‑sensitive on Linux/macOS).
• Network latency: Remote animations load over HTTP. Provide a placeholder or fallback UI while the file downloads.
• Version compatibility: The package API can change between releases. Pin a version in pubspec.yaml if you need stability.
• Performance: Very large JSON files may impact frame rates on low‑end devices. Optimize the source file in LottieFiles or Adobe After Effects before exporting.

Tip: Keep the Lottie integration behind a thin abstraction (e.g., LottieService) so you can swap the implementation or mock it in tests without touching UI code.

Testing Lottie Widgets

Because the widget renders a Canvas, you can verify that it builds without errors using a standard widget test:

testWidgets('Lottie asset loads', (WidgetTester tester) async {
  await tester.pumpWidget(const MaterialApp(home: Lottie.asset('assets/animations/hello.json')));
  // Allow the animation to load.
  await tester.pumpAndSettle();
  expect(find.byType(Lottie), findsOneWidget);
});

Conclusion

The lottie Flutter package offers a quick path to professional‑grade animations while keeping your codebase clean. Follow the installation steps, respect asset declarations, and isolate the dependency behind an app‑specific boundary for maintainable code.

Frequently Asked Questions

What is the lottie Flutter package used for?

It renders Lottie JSON animation files in Flutter apps, allowing designers to ship vector‑based motion graphics without writing custom animation code.

How do I add the lottie package to my project?

Run <code>flutter pub add lottie</code> in your terminal, then run <code>flutter pub get</code>. The package will be listed in your <code>pubspec.yaml</code>.

Can I load animations from a remote URL?

Yes. Use <code>Lottie.network('https://example.com/animation.json')</code>. Provide a placeholder while the file downloads to avoid a blank space.

How can I control playback (play, pause, seek)?

Create an <code>AnimationController</code> and pass it to <code>Lottie.asset</code> or <code>Lottie.network</code> via the <code>controller</code> parameter. Use the controller’s methods (<code>forward</code>, <code>stop</code>, <code>repeat</code>, etc.) to manage playback.

What should I watch out for when using Lottie in production?

Verify asset paths, test network latency handling, pin a stable package version, and keep an eye on animation file size to maintain performance on low‑end devices.