lottie_plus 1.0.0

A high-performance Lottie animation package for Flutter with advanced interactions, gesture presets, state machines, runtime theming, hero transitions, multi-tier caching, and production-ready analytics.

lottie_plus

A high-performance, feature-rich Lottie animation package for Flutter. Redesigned for production-scale apps with complex interactions, advanced state management, and deep observability.

---

🚀 Why lottie_plus?

Standard Lottie libraries are excellent for simple playback, but often fall short when building complex, production-grade user experiences. lottie_plus fills those gaps:

Feature	Standard Lottie	lottie_plus
User Interactions	Requires manual AnimationController	Built-in (Drag, Scroll, Swipe, Pinch)
App State Sync	Manual frame/marker math	Logic-Driven (Enum-to-Marker State Machine)
Sequencing	Juggling multiple widgets/controllers	Native Composer (Chained clips + Layered overlays)
Theming	Verbose ValueDelegate lists	Automatic (Apply light/dark/brand themes)
Caching	Memory only (Clears on restart)	Multi-Tier (Memory + Persistent Disk Cache)
Observability	Console logs only	Visual Inspector (Dedicated DevTools Tab)
Analytics	None	Built-in Tracking (Completion/Engagement metrics)

---

🎨 Powerful Animation Features

lottie_plus is designed for developers who need to move beyond simple "play/pause" controls. It provides high-level abstractions for common UI patterns.

🎮 Drive Progress via Interactions

Map user input directly to animation frames without writing any AnimationController boilerplate.

• Interaction.drag: Drive progress with a drag gesture.
• Interaction.scroll: Tie animation frames to a scroll position.
• Interaction.swipe: Map progress to horizontal or vertical swipes.

Lottie.asset(
  'assets/interaction.json',
  interaction: Interaction.drag,
)

🧠 Logic-Driven State Machines

Map your application's logical states directly to Lottie markers. The widget handles all the math and transitions automatically when your app state changes.

LottieStateMachine.asset(
  'assets/auth.json',
  state: currentAuthState, // e.g., AuthState.loading
  states: {
    AuthState.idle: LottieState(marker: 'idle'),
    AuthState.loading: LottieState(marker: 'loading', loop: true),
    AuthState.success: LottieState(marker: 'success'),
  },
);

🎬 Sequence with the Composer

Chain multiple Lottie files into a single, synchronized flow. Perfect for onboarding or multi-step checkout processes. It handles crossfades and layered overlays (like confetti) effortlessly.

Composer(
  children: [
    ComposerClip.asset('step1.json'),
    ComposerClip.asset('step2.json', overlap: Duration(ms: 500)),
    ComposerClip.asset('confetti.json', layered: true),
  ],
);

🎭 Runtime Theming

Change colors, strokes, gradients, and shadows at runtime. No more manual ValueDelegate lists for every layer—simply apply a theme and lottie_plus does the rest.

Lottie.asset(
  'assets/ui.json',
  theme: LottieTheme.dark, // Or custom LottieTheme.brand(primary: Colors.blue)
);

---

🛠 Professional DevTools & Observability

lottie_plus comes with a dedicated Lottie Inspector extension for the Flutter DevTools. It provides a "Chrome-like" inspection experience for your animations.

🔍 Lottie Inspector Tab

Open DevTools in debug mode to access a specialized tab for tuning your animations in real-time:

• Frame Scrubber: Pinpoint exact frames and view marker boundaries.
• Layer Hierarchy: Inspect the full layer tree and identify performance bottlenecks.
• Memory Stats: View the size and cost of embedded images and cached frames.
• Speed Controls: Tune playback speed (0.1x to 4.0x) without restarting the app.

Enable the extension in your devtools_options.yaml:

extensions:
  - lottie_plus: true

📊 Production Analytics

Track how users interact with your animations in the wild. Measure completion rates, abandonment points, and engagement metrics using a simple callback.

Lottie.asset(
  'assets/paywall.json',
  analyticsId: 'premium_onboarding',
  onAnalyticsEvent: (event) {
    // Pipe to Firebase, Mixpanel, etc.
    print("${event.type}: ${event.animationId} at progress ${event.progress}");
  },
);

---

⚡ Performance & Caching

Multi-Tier Smart Cache

Go beyond memory caching. lottie_plus includes a persistent disk tier that allows for instant repeat loads and offline playback.

• Memory Tier: LRU cache for ultra-fast access to active animations.
• Smart Disk Tier: Persists raw bytes across app restarts.
• Prefetching: Warm up the cache for heavy assets before they are shown.

// Initialize once at app start
SmartCache.install(SmartCache(disk: 500.mb));

// Prefetch a network asset
await LottiePrefetch.network(['https://example.com/huge_animation.json']);

---

Getting Started

1. Add lottie_plus to your pubspec.yaml.
2. (Optional) Initialize SmartCache in your main() function.
3. Start animating!

import 'package:lottie_plus/lottie_plus.dart';

void main() {
  SmartCache.install(SmartCache());
  runApp(MyApp());
}

Platform Support

Android	iOS	Web	macOS	Windows	Linux
✅	✅	✅	✅	✅	✅

---

License

MIT License. See LICENSE for details.