Cached network lottie

pub package License: MIT

A Flutter widget to load and cache both .json and .lottie animation files from the network.

Features

  • Dual Format Support: Works with both .json and .lottie files automatically
  • Asset Caching: Caches both animation files and referenced image assets
  • Flexible Configuration: Supports custom cache managers and HTTP headers
  • Drop-in Replacement: Compatible with existing lottie package API

Platform Support

Platform JSON (.json) DotLottie (.lottie) Telegram Stickers (.tgs)
iOS ✅ ✅ ✅
Android ✅ ✅ ✅
macOS ✅ ✅ ✅
Windows ✅ ⏳ ✅
Linux ✅ ⏳ ✅
Web ✅ ✅ ✅

Note: For detailed DotLottie platform support, see the dotlottie_flutter package documentation.

How to use

Basic Usage

The widget automatically detects the file format and uses the appropriate renderer:

import 'package:cached_network_lottie/cached_network_lottie.dart';

// Lottie JSON
CachedNetworkLottie(
  'https://lottie.host/fc235b2d-2132-4271-82af-f93b72c2e410/Og3p09zjT5.json',
  width: 180,
  height: 180,
)

// DotLottie (.lottie)
CachedNetworkLottie(
  'https://lottie.host/95d9b5d7-505f-4582-95b8-0ac7564d9585/rjoHaSls9v.lottie',
  width: 180,
  height: 180,
)

// Telegram Stickers (.tgs)
CachedNetworkLottie(
  'https://telegram.org/file/464001484/1/bzi7gr7XRGU.10147/815df2ef527132dd23',
  width: 180,
  height: 180,
)

Custom Cache Manager and Headers

CachedNetworkLottie(
  'https://lottie.host/fc235b2d-2132-4271-82af-f93b72c2e410/Og3p09zjT5.json',
  cacheManager: myCacheManager,
  headers: {'Authorization': 'Bearer token'},
  width: 200,
  height: 200,
)

LottieBuilder Type (JSON Only)

If you need a LottieBuilder type (e.g., for widgets that specifically require LottieBuilder), use the .builder() method. This only supports .json files:

LottieBuilder animation = CachedNetworkLottie.builder(
  'https://example.com/anim.json',
  width: 200,
  height: 200,
  repeat: true,
  controller: myAnimationController,
);

Error Handling

CachedNetworkLottie(
  'https://lottie.host/95d9b5d7-505f-4582-95b8-0ac7564d9585/rjoHaSls9v.lottie',
  width: 200,
  height: 200,
  errorBuilder: (context, error, stackTrace) {
    return Icon(Icons.error);
  },
)

Advanced Usage

CachedNetworkLottie(
  'https://example.com/anim.json',
  // Common parameters
  width: 200,
  height: 200,
  fit: BoxFit.contain,
  alignment: Alignment.center,

  // Animation controls
  animate: true,
  repeat: true,
  reverse: false,

  // DotLottie Advanced features
  stateMachineId: 'StateMachine1',
  themeId: "Dark Mode",
  animationId: "Animation1",

  // Caching
  cacheManager: DefaultCacheManager(),
  headers: {'Custom-Header': 'value'},
)

Example

Check out the example directory for a complete demo app showing:

  • JSON Lottie animations
  • DotLottie animations
  • Telegram Stickers

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Libraries

cached_network_lottie