Lottie for Flutter

https://github.com/xvrh/lottie-flutter
Admin
Lottie for Flutter is a mobile library that parses Adobe After Effects animations exported as JSON...
Tokens:65,125
Snippets:406
Trust Score:9.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Listing markers

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Example of loading a Lottie composition and printing the start and end progress of each marker.

```APIDOC
## Listing markers

### Description
Example of loading a Lottie composition and printing the start and end progress of each marker.

### Code
```dart
final composition = await AssetLottie('assets/TwitterHeartButton.json').load();

for (final marker in composition.markers) {
  print('${marker.name}: ${marker.start.toStringAsFixed(2)}'
      ' -> ${marker.end.toStringAsFixed(2)}');
}
```
```

--------------------------------

### Listing markers

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Example of listing markers. Loads a Lottie asset and prints each marker's name, start, and end progress values.

```dart
final composition = await AssetLottie('assets/TwitterHeartButton.json').load();

for (final marker in composition.markers) {
  print('${marker.name}: ${marker.start.toStringAsFixed(2)}'
      ' -> ${marker.end.toStringAsFixed(2)}');
}
```

--------------------------------

### LottieOptions Usage Examples

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-options.md

Examples of using LottieOptions with Lottie.asset and Lottie.network.

```APIDOC
## LottieOptions Usage Examples

### Description
Examples of using LottieOptions with Lottie.asset and Lottie.network.

### Example 1: Basic use
```dart
Lottie.asset(
  'assets/overlapping.json',
  options: const LottieOptions(
    enableMergePaths: true,
  ),
)
```

### Example 2: Layer opacity with render cache
```dart
Lottie.network(
  'https://example.com/glass.json',
  options: const LottieOptions(
    enableApplyingOpacityToLayers: true,
  ),
  frameRate: FrameRate(30),
  renderCache: RenderCache.drawingCommands,
)
```

> Note: `RawLottie`/`RenderLottie` require a concrete `FrameRate` (not `FrameRate.max`) when a `renderCache` is set.
```

--------------------------------

### DropShadow

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/drop-shadow.md

Documentation for the DropShadow class, including its constructor, parameters, methods, and usage examples.

```APIDOC
## DropShadow

### Description
An immutable descriptor for a Lottie drop-shadow effect, used with `ValueDelegate.dropShadow` and `LottieProperty.dropShadow`.

### Constructor

```dart
const DropShadow({
  required this.color,
  required this.direction,
  required this.distance,
  required this.radius,
});
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| color | `Color` | yes | — | Shadow color. |
| direction | `double` | yes | — | Shadow direction in degrees (After Effects convention). |
| distance | `double` | yes | — | Offset distance of the shadow, in px. |
| radius | `double` | yes | — | Blur radius of the shadow. |

### Methods

#### `copyWith`

```dart
DropShadow copyWith({
  Color? color,
  double? direction,
  double? distance,
  double? radius,
}) {
  return DropShadow(
    color: color ?? this.color,
    direction: direction ?? this.direction,
    distance: distance ?? this.distance,
    radius: radius ?? this.radius,
  );
}
```

Returns a new `DropShadow` with the given fields replaced and the rest copied.

#### Equality and printing

```dart
@override
bool operator ==(other) {
  return other is DropShadow &&
      other.color == color &&
      other.direction == direction &&
      other.distance == distance &&
      other.radius == radius;
}

@override
int get hashCode => Object.hash(color, direction, distance, radius);

@override
String toString() =>
    'DropShadow(color: $color, direction: $direction, '
    'distance: $distance, radius: $radius)';
```

Structural value equality on all four fields.

### Related symbols

- The sentinel default is `LottieProperty.dropShadow` — a const `DropShadow(color: Color(0x00000000), direction: 0, distance: 0, radius: 0)`.
- Created from animation data by `DropShadowEffect`, parsed by `lib/src/parser/drop_shadow_effect_parser.dart`. The effect itself applies a blur-and-offset shadow — see `DropShadowContent`/`lib/src/animation/content/...` rendering code.

### Examples

#### Static shadow override

```dart
Lottie.asset(
  'assets/card.json',
  delegates: LottieDelegates(
    values: [
      ValueDelegate.dropShadow(
        const ['Card', 'Shadow'],
        value: const DropShadow(
          color: Color(0x80000000),
          direction: 90,
          distance: 4,
          radius: 8,
        ),
      ),
    ],
  ),
)
```

#### Animated shadow via callback and copyWith

```dart
Lottie.network(
  'https://example.com/hero.json',
  delegates: LottieDelegates(
    values: [
      ValueDelegate.dropShadow(
        const ['Hero', 'Shadow'],
        callback: (frameInfo) {
          // Grow the radius with overall progress.
          final base = frameInfo.startValue ??
              const DropShadow(color: Colors.black, direction: 90, distance: 2, radius: 4);
          return base.copyWith(radius: 4 + frameInfo.overallProgress * 20);
        },
      ),
    ],
  ),
)
```
```

--------------------------------

### DotLottie (.lottie) example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to select the correct .json file from a dotlottie archive by providing a custom decoder.

```dart
import 'example/lib/examples/dotlottie.dart#example';
```

--------------------------------

### Manual load with a custom provider

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/providers.md

Example of manually loading a Lottie composition and displaying it with a FutureBuilder.

```APIDOC
## Manual load with a custom provider (custom loading)

### Description
Example of manually loading a Lottie composition and displaying it with a `FutureBuilder`.

### Code
```dart
class MyWidget extends StatefulWidget {
  const MyWidget({super.key});

  @override
  State<MyWidget> createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late final Future<LottieComposition> _composition;

  @override
  void initState() {
    super.initState();
    _composition = AssetLottie('assets/LottieLogo1.json').load();
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<LottieComposition>(
      future: _composition,
      builder: (context, snapshot) {
        if (snapshot.hasError) return const Text('Failed to load');
        final composition = snapshot.data;
        if (composition == null) {
          return const Center(child: CircularProgressIndicator());
        }
        return Lottie(composition: composition);
      },
    );
  }
}
```
```

--------------------------------

### Telegram Stickers (.tgs) example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to load TGS files by providing a special decoder.

```dart
import 'example/lib/examples/telegram_stickers.dart#example';
```

--------------------------------

### Custom loading example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to load and parse a Lottie composition from a JSON file using AssetLottie, NetworkLottie, or MemoryLottie for full control over loading.

```dart
import 'example/lib/examples/custom_load.dart#example';
```

--------------------------------

### Network load with custom headers, background parsing and custom images

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/providers.md

Example of loading a network Lottie with custom headers, background parsing, and custom image provider factory.

```APIDOC
## Network load with custom headers, background parsing and custom images

### Description
Example of loading a network Lottie with custom headers, background parsing, and a custom image provider factory.

### Code
```dart
final composition = await NetworkLottie(
  'https://api.example.com/anim.json',
  headers: {'Authorization': 'Bearer $token'},
  backgroundLoading: true,
  imageProviderFactory: (asset) => asset.id == 'img_0'
      ? NetworkImage('https://cdn.example.com/hero.png')
      : null,
  decoder: LottieComposition.decodeGZip,
).load();
```
```

--------------------------------

### Frame export example

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-drawable.md

Shows how to render a single frame of a Lottie composition to a ui.Image using LottieDrawable.

```APIDOC
## Frame export with progress check

```dart
Future<ui.Image> renderFrame(
  LottieComposition composition,
  double progress,
  Size size,
) async {
  final drawable = LottieDrawable(composition);
  final recorder = ui.PictureRecorder();
  final canvas = Canvas(recorder);

  // setProgress returns true when the frame changed; ignore here, we always draw.
  drawable.setProgress(progress);
  drawable.draw(canvas, Offset.zero & size, fit: BoxFit.contain);

  final picture = recorder.endRecording();
  return picture.toImage(size.width.toInt(), size.height.toInt());
}
```
```

--------------------------------

### Custom AnimationController example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to take full control over the animation by providing your own AnimationController, enabling start/stop, forward/backward, and looping between specific points.

```dart
import 'example/lib/examples/animation_controller.dart';
```

--------------------------------

### Custom painting example

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-drawable.md

Shows how to use LottieDrawable in a custom painter to draw multiple frames as a contact sheet.

```APIDOC
## Custom painting (from the project README)

```dart
class MyPainter extends CustomPainter {
  final LottieDrawable drawable;

  MyPainter(LottieComposition composition) : drawable = LottieDrawable(composition);

  @override
  void paint(Canvas canvas, Size size) {
    // Draw 40 frames as a grid of contact-sheet cells.
    var frameCount = 40;
    var columns = 10;
    for (var i = 0; i < frameCount; i++) {
      var destRect = Offset(i % columns * 50.0, i ~/ 10 * 80.0) & (size / 5);
      drawable
        ..setProgress(i / frameCount)
        ..draw(canvas, destRect);
    }
  }

  @override
  bool shouldRepaint(covariant CustomPainter oldDelegate) => true;
}
```
```

--------------------------------

### LottieDelegates

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-delegates.md

Documentation for the LottieDelegates class, including its constructor, parameters, equality, defaultTextStyleDelegate method, relations, and usage examples.

```APIDOC
## LottieDelegates

### Description
An immutable bundle of runtime customization callbacks passed to `Lottie`, `LottieBuilder`, `RawLottie` or `LottieDrawable`: dynamic text replacement, font-family mapping, per-frame value callbacks and image replacement.

### Constructor

```dart
const LottieDelegates({this.text, this.textStyle, this.values, this.image});
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| text | `String Function(String)?` | no | `null` | Called with the original text of a text layer; return the text to display instead (e.g. a translation). |
| textStyle | `TextStyle Function(LottieFontStyle)?` | no | `null` | Maps the font family/style declared in the JSON to a base `TextStyle` (e.g. your asset font). When null, `defaultTextStyleDelegate` is used and the JSON font family is used as-is. |
| values | `List<ValueDelegate>?` | no | `null` | Value delegates modifying animation properties at runtime; each targeting a `KeyPath`. |
| image | `ui.Image? Function(LottieComposition, LottieImageAsset)?` | no | `null` | Called with the composition and the image asset; return an image to replace it, or `null` to use the default loaded image. |

### Equality

```dart
@override
bool operator ==(Object other) =>
    identical(this, other) ||
    other is LottieDelegates &&
        text == other.text &&
        textStyle == other.textStyle &&
        values == other.values;

@override
int get hashCode => Object.hash(text, textStyle, values);
```

Equality ignores `image` (a deliberate asymmetry in the source). This matters for widget rebuilds: a `LottieDelegates` equal under `==` does not retrigger value-delegate re-resolution in `LottieDrawable`.

### `defaultTextStyleDelegate`

```dart
TextStyle defaultTextStyleDelegate(LottieFontStyle font) {
  var style = font.style.toLowerCase();

  var fontStyle = style.contains('italic') ? FontStyle.italic : null;

  FontWeight? fontWeight;
  if (style.contains('semibold') || style.contains('semi bold')) {
    fontWeight = FontWeight.w600;
  } else if (style.contains('bold')) {
    fontWeight = FontWeight.bold;
  }
  return TextStyle(
    fontFamily: font.fontFamily,
    fontStyle: fontStyle,
    fontWeight: fontWeight,
  );
}
```

The fallback used by `LottieDrawable.getTextStyle` when no `textStyle` callback is provided. Maps style strings: contains `italic` → `FontStyle.italic`; contains `semibold`/`semi bold` → `FontWeight.w600`; contains `bold` → `FontWeight.bold`. **Not re-exported** from `lib/lottie.dart` (only used internally as the default).

### Relations

- `values` entries are of type `ValueDelegate`; they use `LottieProperty` sentinels and receive `LottieFrameInfo` objects.
- `image` overrides what `LottieDrawable.getImageAsset` returns; return `null` to fall back to `LottieImageAsset.loadedImage` (loaded by the provider).
- The `textStyle` callback receives a `LottieFontStyle`.

### Examples

#### Dynamic text and font mapping

```dart
Lottie.asset(
  'assets/hello.json',
  delegates: LottieDelegates(
    text: (initialText) => _translator.translate(initialText),
    textStyle: (font) => TextStyle(
      fontFamily: 'MyAssetFont',
      fontWeight: FontWeight.w600,
    ),
  ),
)
```

#### Per-frame values and image swap

```dart
Lottie.network(
  'https://example.com/scene.json',
  delegates: LottieDelegates(
    values: [
      ValueDelegate.color(const ['lake', 'fill'], value: Colors.blue),
      ValueDelegate.opacity(
        const ['**', 'fill'],
        callback: (frameInfo) => (0.5 * frameInfo.overallProgress * 100).round(),
      ),
    ],
    image: (composition, image) {
      if (image.id == 'img_0' && isMouseOver) {
        return myCustomImage; // ui.Image
      }
      return null; // use the default loaded image
    },
  ),
)
```

#### Caveat: equality ignores `image`

Because `==`/`hashCode` ignore the `image` callback, two `LottieDelegates` differing only in `image` are considered equal — the widget update path (`LottieDrawable.delegates` setter) will not re-apply them. If you need hot-swapping of the image delegate, change another field (e.g. pass a new `List` for `values`) or recreate the whole `Lottie` with a different `key`.
```

--------------------------------

### Custom drawing example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to draw a LottieComposition on a custom Canvas at a specific frame, position, and size.

```dart
import 'example/lib/examples/custom_draw.dart#example';
```

--------------------------------

### Cache control

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/providers.md

Example of controlling the Lottie cache size and evicting entries.

```APIDOC
## Cache control

### Description
Example of lowering the shared cache size and evicting a specific entry.

### Code
```dart
// Lower the shared cache and prune a specific entry.
void pruneCache({required String url}) {
  Lottie.cache.maximumSize = 50;
  Lottie.cache.evict(NetworkLottie(url));
}
```
```

--------------------------------

### Playing between two markers

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Example of using markers to play a specific section of a Lottie animation by setting the controller's value and animating to the end marker's start.

```APIDOC
## Playing between two markers

### Description
Example of using markers to play a specific section of a Lottie animation by setting the controller's value and animating to the end marker's start.

### Code
```dart
class MarkerPlayer extends StatefulWidget {
  const MarkerPlayer({super.key, required this.composition});

  final LottieComposition composition;

  @override
  State<MarkerPlayer> createState() => _MarkerPlayerState();
}

class _MarkerPlayerState extends State<MarkerPlayer>
    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) {
    final composition = widget.composition;
    final start = composition.getMarker('Left');
    final end = composition.getMarker('Right');

    return Lottie(
      composition: composition,
      controller: _controller,
      onLoaded: (_) {
        if (start != null && end != null) {
          _controller
            ..value = start.start
            ..animateTo(end.start, duration: composition.duration * (end.start - start.start));
        }
      },
    );
  }
}
```

### Notes
`Lottie` has no `onLoaded` parameter — the snippet above uses `Lottie.composition` directly (already loaded), so the "onLoaded" wiring in the example is illustrative only. Use `LottieBuilder.asset(..., onLoaded: ...)` when the composition is loaded asynchronously.
```

--------------------------------

### Layer opacity with render cache

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-options.md

Non-trivial example enabling layer-level opacity with a render cache. Note that RawLottie/RenderLottie require a concrete FrameRate (not FrameRate.max) when a renderCache is set.

```dart
Lottie.network(
  'https://example.com/glass.json',
  options: const LottieOptions(
    enableApplyingOpacityToLayers: true,
  ),
  frameRate: FrameRate(30),
  renderCache: RenderCache.drawingCommands,
)
```

--------------------------------

### Load DotLottie (.lottie) with custom decoder and filePicker

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.md

Loads a DotLottie (.lottie) archive by providing a custom decoder that selects the correct .json file. The decoder uses LottieComposition.decodeZip with a filePicker that finds the first file whose name starts with 'animations/' and ends with '.json'.

```dart
class Example extends StatelessWidget {
  const Example({super.key});

  @override
  Widget build(BuildContext context) {
    return Lottie.asset('assets/cat.lottie', decoder: customDecoder);
  }
}

Future<LottieComposition?> customDecoder(List<int> bytes) {
  return LottieComposition.decodeZip(
    bytes,
    filePicker: (files) {
      return files.firstWhereOrNull(
        (f) => f.name.startsWith('animations/') && f.name.endsWith('.json'),
      );
    },
  );
}
```

--------------------------------

### Marker Constructor

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Creates a Marker instance with the given composition, name, start frame, and duration in frames. Typically instantiated by the parser and accessed via composition.markers or composition.getMarker().

```APIDOC
## Marker Constructor

### Description
Creates a Marker instance with the given composition, name, start frame, and duration in frames. Typically instantiated by the parser and accessed via composition.markers or composition.getMarker().

### Constructor
```dart
Marker(
  this._composition,
  this.name, {
  required this.startFrame,
  required this.durationFrames,
});
```

### Parameters
- `_composition` (LottieComposition) - Required - Owning composition; used to normalize frames into 0..1 progress (`start`/`end`).
- `name` (String) - Required - Marker name (case-insensitive matching).
- `startFrame` (double) - Required - First frame of the marker, in composition frame coordinates.
- `durationFrames` (double) - Required - Marker length in frames.

### Notes
Instances are created by the parser; consumers normally obtain them via `composition.markers` or `composition.getMarker(name)`.
```

--------------------------------

### Dynamic text and font mapping with LottieDelegates

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-delegates.md

Example of using LottieDelegates with Lottie.asset to dynamically translate text and map font styles. The text callback receives the original text and returns a translation; the textStyle callback maps the font to a custom asset font with weight w600.

```dart
Lottie.asset(
  'assets/hello.json',
  delegates: LottieDelegates(
    text: (initialText) => _translator.translate(initialText),
    textStyle: (font) => TextStyle(
      fontFamily: 'MyAssetFont',
      fontWeight: FontWeight.w600,
    ),
  ),
)
```

--------------------------------

### Per-frame values and image swap with LottieDelegates

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-delegates.md

Example of using LottieDelegates with Lottie.network to modify animation properties per-frame and swap images. The values list uses ValueDelegate.color and ValueDelegate.opacity with KeyPaths; the image callback returns a custom image for a specific asset when a condition is met, otherwise null to use the default.

```dart
Lottie.network(
  'https://example.com/scene.json',
  delegates: LottieDelegates(
    values: [
      ValueDelegate.color(const ['lake', 'fill'], value: Colors.blue),
      ValueDelegate.opacity(
        const ['**', 'fill'],
        callback: (frameInfo) => (0.5 * frameInfo.overallProgress * 100).round(),
      ),
    ],
    image: (composition, image) {
      if (image.id == 'img_0' && isMouseOver) {
        return myCustomImage; // ui.Image
      }
      return null; // use the default loaded image
    },
  ),
)
```

--------------------------------

### Playing between two markers

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Example of playing between two markers. Note: Lottie has no onLoaded parameter; the snippet uses Lottie.composition directly (already loaded), so the onLoaded wiring is illustrative only. Use LottieBuilder.asset(..., onLoaded: ...) when the composition is loaded asynchronously.

```dart
class MarkerPlayer extends StatefulWidget {
  const MarkerPlayer({super.key, required this.composition});

  final LottieComposition composition;

  @override
  State<MarkerPlayer> createState() => _MarkerPlayerState();
}

class _MarkerPlayerState extends State<MarkerPlayer>
    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) {
    final composition = widget.composition;
    final start = composition.getMarker('Left');
    final end = composition.getMarker('Right');

    return Lottie(
      composition: composition,
      controller: _controller,
      onLoaded: (_) {
        if (start != null && end != null) {
          _controller
            ..value = start.start
            ..animateTo(end.start, duration: composition.duration * (end.start - start.start));
        }
      },
    );
  }
}
```

--------------------------------

### fromBytes static method

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-composition.md

Main entry point: tries the custom decoder (default decodeZip), and if it returns null falls back to plain JSON parsing. The archive and path packages are used by the zip decoder.

```dart
static Future<LottieComposition> fromBytes(
  List<int> bytes, {
  LottieDecoder? decoder,
}) async {
  decoder ??= decodeZip;
  var compositionFuture = await decoder(bytes);
  if (compositionFuture != null) {
    return compositionFuture;
  }
  return parseJsonBytes(bytes);
}
```

--------------------------------

### Use a custom AnimationController with Lottie.asset

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.md

Provides a custom AnimationController to gain full control over the animation, such as starting, stopping, playing forward/backward, and looping between specific points. The controller is configured with the Lottie composition's duration and started in the onLoaded callback.

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

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

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with TickerProviderStateMixin {
  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 MaterialApp(
      home: Scaffold(
        body: ListView(
          children: [
            Lottie.asset(
              'assets/LottieLogo1.json',
              controller: _controller,
              onLoaded: (composition) {
                // Configure the AnimationController with the duration of the
                // Lottie file and start the animation.
                _controller
                  ..duration = composition.duration
                  ..forward();
              },
            ),
          ],
        ),
      ),
    );
  }
}
```

--------------------------------

### FrameRate

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/frame-rate.md

Documentation for the FrameRate class, including its constructor, constants, properties, methods, and usage examples.

```APIDOC
## FrameRate

### Description
An immutable value controlling how many frames per second a Lottie animation is rendered at. Lower frame rates preserve battery by doing less rendering work.

### Constructor

```dart
const FrameRate(this.framesPerSecond) : assert(framesPerSecond > 0);
```

### Constants

- `FrameRate.max` - Sentinel (`framesPerSecond == 0`): advance the animation on every display frame.
- `FrameRate.composition` - Sentinel (`framesPerSecond == -1`): use the frame rate exported by After Effects (the default behavior).

### Properties

- `framesPerSecond` (double) - The requested FPS. The generative constructor asserts `framesPerSecond > 0`.

### Methods

#### `resolveFps`

```dart
double? resolveFps(double? compositionFrameRate) {
  if (this == max) return null;
  var fps = this == composition ? compositionFrameRate : framesPerSecond;
  if (fps == null || !fps.isFinite || fps <= 0) return null;
  return fps;
}
```

Returns the effective frames per second for a composition whose own rate is `compositionFrameRate`, or `null` when every display frame should be rendered (`max`) or no usable rate exists (missing, non-finite or non-positive composition rate). This is used by `LottieComposition.roundProgress` and `LottieDrawable.setProgress` to quantize progress.

#### `hashCode` / `operator ==` / `toString`

```dart
@override
int get hashCode => framesPerSecond.hashCode;

@override
bool operator ==(other) =>
    other is FrameRate && other.framesPerSecond == framesPerSecond;

@override
String toString() {
  return 'FrameRate(${switch (framesPerSecond) {
    0 => 'max',
    -1 => 'composition',
    _ => framesPerSecond,
  }})';
}
```

Value equality on `framesPerSecond`; `toString` renders `FrameRate(max)`, `FrameRate(composition)` or `FrameRate(<fps>)`.

### Examples

#### Selecting a frame rate

```dart
Lottie.asset(
  'anim.json',
  // Use the exported frame rate (default)
  frameRate: FrameRate.composition,
  // Use the device frame rate (up to 120 FPS)
  frameRate: FrameRate.max,
  // Cap to a specific frame rate
  frameRate: FrameRate(10),
)
```

#### Programmatic rounding

```dart
final composition = await AssetLottie('anim.json').load();

// Quantize progress to the composition's own frame grid:
final rounded = composition.roundProgress(
  0.501,
  frameRate: FrameRate.composition,
);

// Quantize to a 30 FPS grid:
final rounded30 = composition.roundProgress(0.501, frameRate: FrameRate(30));

// FrameRate.max bypasses quantization:
final fps = FrameRate.max.resolveFps(composition.frameRate); // null
```
```

--------------------------------

### LottieImageAsset Constructor

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-image-asset.md

Creates a LottieImageAsset instance with required parameters for width, height, id, fileName, and dirName.

```APIDOC
## LottieImageAsset Constructor

### Description
Creates a LottieImageAsset instance describing an embedded image in a Lottie composition.

### Constructor
```dart
LottieImageAsset({
  required this.width,
  required this.height,
  required this.id,
  required this.fileName,
  required this.dirName,
});
```

### Parameters
- **width** (`int`) - Required - Image width in px (declared in the JSON).
- **height** (`int`) - Required - Image height in px.
- **id** (`String`) - Required - Unique asset id referenced by image layers.
- **fileName** (`String`) - Required - File name (may be a `data:` URI — see `fromDataUri`).
- **dirName** (`String`) - Required - Directory name of the image inside the animation's assets.

### Fields
- **loadedImage** (`ui.Image?`) - Mutable: the decoded image, populated by providers during `load()` (via `loadImage`); `null` until decoded or after a decode failure.

### Example: Replacing an image at runtime
```dart
Lottie.asset(
  'assets/data.json',
  delegates: LottieDelegates(
    image: (composition, image) {
      if (image.id == 'img_0' && isMouseOver) {
        return myHoverImage; // ui.Image
      }
      return null; // default: composition.images[image.id].loadedImage
    },
  ),
)
```

### Example: Inspecting assets and preloading an image
```dart
final composition = await AssetLottie('assets/scene.json').load();

for (final entry in composition.images.entries) {
  final asset = entry.value;
  debugPrint('${entry.key}: ${asset.width}x${asset.height}'
      ' @ ${asset.dirName}/${asset.fileName}'
      ' loaded=${asset.loadedImage != null}');
}
```
```

--------------------------------

### startFrame

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-composition.md

First frame.

```APIDOC
## startFrame

### Description
First frame.

### Getter
```dart
double get startFrame
```

### Source
`lib/src/composition.dart:201`
```

--------------------------------

### Marker Members

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/marker.md

Properties and methods of the Marker class, including name, startFrame, durationFrames, matchesName, start, and end.

```APIDOC
## Marker Members

### Description
Properties and methods of the Marker class, including name, startFrame, durationFrames, matchesName, start, and end.

### Members

#### `name`
- Signature: `final String name`
- Description: Marker name.

#### `startFrame`
- Signature: `final double startFrame`
- Description: Start frame (absolute composition frame).

#### `durationFrames`
- Signature: `final double durationFrames`
- Description: Duration in frames.

#### `matchesName`
- Signature: `bool matchesName(String name)`
- Description: Case-insensitive, whitespace-trimmed name comparison.

#### `start`
- Signature: `double get start`
- Description: Normalized start progress: `(startFrame - composition.startFrame) / composition.durationFrames`.

#### `end`
- Signature: `double get end`
- Description: Normalized end progress: `(startFrame + durationFrames - composition.startFrame) / composition.durationFrames`.
```

--------------------------------

### Provider Constructor Options

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/configuration.md

Constructor options for Lottie providers, including common and provider-specific parameters.

```APIDOC
## Provider Constructor Options

### Description
Common constructor options for all Lottie providers (`AssetLottie`, `NetworkLottie`, `FileLottie`, `MemoryLottie`).

### Common Options
- **imageProviderFactory** (`LottieImageProviderFactory?`) - Optional. Custom `ImageProvider` per embedded image; checked after `data:` URI handling.
- **decoder** (`LottieDecoder?`) - Optional. Custom byte decoder, e.g. `LottieComposition.decodeGZip` for `.tgs`. Defaults to `decodeZip`.
- **backgroundLoading** (`bool?`) - Optional. Parse JSON in a background isolate via `compute(parseJsonBytes, ...)`. Defaults to `false`.

### Provider-Specific Options

#### AssetLottie
- **assetName** (`String`) - Required. Asset key in the bundle.
- **bundle** (`AssetBundle?`) - Optional. Bundle to load from. Defaults to `DefaultAssetBundle.of(context)` or `rootBundle`.
- **package** (`String?`) - Optional. Package prefix `packages/$package/` applied to the key.

#### NetworkLottie
- **url** (`String`) - Required. URL, resolved against `Uri.base`.
- **client** (`http.Client?`) - Optional. Custom HTTP client. If not provided, a client is created and closed internally.
- **headers** (`Map<String, String>?`) - Optional. Request headers.

#### FileLottie
- **file** (`Object`) - Required. `dart:io` `File` (web unsupported — assert).

#### MemoryLottie
- **bytes** (`Uint8List`) - Required. In-memory JSON/zip/tgs bytes.

### Usage Example
```dart
final asset = AssetLottie('assets/anim.json', package: 'my_package');
final network = NetworkLottie('https://example.com/anim.json', headers: {'Authorization': 'Bearer token'});
final file = FileLottie(File('anim.json'));
final memory = MemoryLottie(bytes);
```
```

--------------------------------

### Lottie Widget

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie.md

Documentation for the Lottie widget constructor and its parameters.

```APIDOC
## Lottie Widget

### Description
A StatefulWidget that displays a loaded LottieComposition. If a controller is supplied it drives the animation; otherwise the widget creates an internal AnimationController whose behavior is governed by the animate, repeat and reverse properties. The widget renders through a RawLottie render object and optionally wraps the result in a RepaintBoundary.

### Constructor
```dart
const Lottie({
  super.key,
  required this.composition,
  this.controller,
  this.width,
  this.height,
  this.alignment,
  this.fit,
  bool? animate,
  this.frameRate,
  bool? repeat,
  bool? reverse,
  this.delegates,
  this.options,
  bool? addRepaintBoundary,
  this.filterQuality,
  this.renderCache,
}) : animate = animate ?? true,
     reverse = reverse ?? false,
     repeat = repeat ?? true,
     addRepaintBoundary = addRepaintBoundary ?? true;
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| key | `Key?` | no | — | Widget key. |
| composition | `LottieComposition?` | yes (`required`) | — | The composition to animate. Can be parsed asynchronously with `LottieComposition.fromBytes`. A null composition renders an empty box. |
| controller | `Animation<double>?` | no | `null` (auto-created controller) | Custom animation controller; its value is mapped to the composition `progress` (0.0–1.0). |
| width | `double?` | no | `null` | If non-null, requires the composition to have this width; otherwise the composition picks a size preserving its intrinsic aspect ratio. |
| height | `double?` | no | `null` | If non-null, requires the composition to have this height. |
| alignment | `AlignmentGeometry?` | no | `null` (rendered as `Alignment.center`) | How to align the composition within its bounds. |
| fit | `BoxFit?` | no | `null` | How to inscribe the composition into the allocated layout space. |
| animate | `bool?` | no | `true` | Whether the automatic animation plays (no effect when `controller` is non-null). |
| frameRate | `FrameRate?` | no | `null` (i.e. `FrameRate.composition`) | Frames per second to render; see [FrameRate](frame-rate.md). |
| repeat | `bool?` | no | `true` | Loop the automatic animation (no effect if `animate` is false or `controller` is set). |
| reverse | `bool?` | no | `false` | Ping-pong loop of the automatic animation (no effect if `animate`/`repeat` are false or `controller` is set). |
| delegates | `LottieDelegates?` | no | `null` | Text delegate, value callbacks and text-style factory; see [LottieDelegates](lottie-delegates.md). |
| options | `LottieOptions?` | no | `null` | Feature toggles (`enableMergePaths`, `enableApplyingOpacityToLayers`); see [LottieOptions](lottie-options.md). |
| addRepaintBoundary | `bool?` | no | `true` | Wrap the animation in a `RepaintBoundary` to isolate it in its own layer. |
| filterQuality | `FilterQuality?` | no | `null` (renders as `FilterQuality.low`) | Quality of image layers; `FilterQuality.high` is highest quality but slowest. |
| renderCache | `RenderCache?` | no | `null` | Opt-in frame cache; see [RenderCache](render-cache.md). |

### Return type
`Lottie` (a `StatefulWidget`). The returned widget tree is a `RawLottie` optionally wrapped in a `RepaintBoundary` (`lib/src/lottie.dart:557-573`).
```

--------------------------------

### Interpolating between keyframes with ValueDelegate.cornerRadius

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/value-delegate.md

Interpolates between keyframe start and end values using interpolatedKeyframeProgress. Note that value and callback are mutually exclusive and will assert if both are provided.

```dart
ValueDelegate<double> sizeDelegate = ValueDelegate.cornerRadius(
  const ['Card', 'Rounded Rect'],
  callback: (frameInfo) {
    final start = frameInfo.startValue ?? 0.0;
    final end = frameInfo.endValue ?? start;
    return start + (end - start) * frameInfo.interpolatedKeyframeProgress;
  },
);

// Note: value and callback are mutually exclusive (assert).
// ValueDelegate.transformRotation(const ['a'], value: 45.0, callback: (f) => 0.0); // asserts
```

--------------------------------

### LottieDrawable

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-drawable.md

Documentation for the LottieDrawable constructor, including its parameters and usage context.

```APIDOC
## LottieDrawable

### Description
Creates a low-level painter that holds a parsed LottieComposition, owns the layer tree, tracks a progress value, and rasterizes the animation onto any Canvas. It is used by RawLottie/Lottie and can be used directly inside a CustomPainter.

### Constructor
```dart
LottieDrawable(this.composition, {LottieDelegates? delegates, this.frameRate})
```

### Parameters
- **composition** (`LottieComposition`) - Required (positional) - The parsed animation.
- **delegates** (`LottieDelegates?`) - Optional - Runtime customization (text, images, value delegates, text style).
- **frameRate** (`FrameRate?`) - Optional - Render frame rate; affects `setProgress` rounding and `progress` step granularity. Defaults to `FrameRate.composition`.

### Notes
The `size` field is derived from `composition.bounds`.
```

--------------------------------

### Modify properties at runtime example

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.template.md

Shows how to modify animation properties at runtime, such as text, color, opacity, and position, using ValueDelegate with static values or callbacks.

```dart
import 'example/lib/examples/simple_dynamic_properties.dart#example';
```

--------------------------------

### decodeZip static method

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-composition.md

Detects a ZIP container (magic bytes 0x50 0x4B) and: 1. Picks the JSON file: either via filePicker(archive.files), else the first file under animations/*.json, else the first .json file whose basename is not manifest.json (i.e. DotLottie .lottie and Lottie .zip images archives). 2. Parses the JSON. 3. Loads each referenced image: first via imageProviderFactory if given, else from the archive via MemoryImage. 4. Collects .ttf files from the archive into composition._fontsToLoad (visible through FontToLoad.getAndClear). Returns null when the bytes are not a ZIP, triggering the JSON fallback in fromBytes.

```dart
static Future<LottieComposition?> decodeZip(
  List<int> bytes, {
  LottieImageProviderFactory? imageProviderFactory,
  ArchiveFile? Function(List<ArchiveFile>)? filePicker,
}) async
```

--------------------------------

### FontToLoad class

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-composition.md

Holds .ttf font bytes discovered inside zip archives by decodeZip. Not re-exported from lib/lottie.dart. The example app uses it to register fonts found in Lottie zips (example/lib/examples/custom_load.dart).

```dart
class FontToLoad {
  final Uint8List bytes;
  final String? family;

  FontToLoad(this.bytes, {this.family});

  static List<FontToLoad>? getAndClear(LottieComposition composition);
}
```

--------------------------------

### RawLottie

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/raw-lottie.md

Documentation for the RawLottie widget constructor and its parameters.

```APIDOC
## RawLottie

### Description
A `LeafRenderObjectWidget` that displays a `LottieDrawable` with explicit `progress`-driven control. It bypasses all autoplay logic — the animation is only advanced when `progress` changes. It is rarely used directly; `Lottie` builds one internally.

### Constructor
```dart
const RawLottie({
  super.key,
  this.composition,
  this.delegates,
  this.options,
  double? progress,
  this.frameRate,
  this.width,
  this.height,
  this.fit,
  AlignmentGeometry? alignment,
  this.filterQuality,
  this.renderCache,
}) : progress = progress ?? 0.0,
     alignment = alignment ?? Alignment.center;
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| key | `Key?` | no | — | Widget key. |
| composition | `LottieComposition?` | no | `null` | The composition to display. |
| delegates | `LottieDelegates?` | no | `null` | Runtime customization (text, values, images, text style). |
| options | `LottieOptions?` | no | `null` | Feature toggles (`enableMergePaths`, `enableApplyingOpacityToLayers`) forwarded to `RenderLottie`. |
| progress | `double?` | no | `0.0` | Animation progress in `[0.0, 1.0]`. |
| frameRate | `FrameRate?` | no | `null` (`FrameRate.composition`) | Frames per second to render. |
| width / height | `double?` | no | `null` | Preferred size; composition keeps intrinsic aspect ratio otherwise. |
| fit | `BoxFit?` | no | `null` | How to inscribe the composition. |
| alignment | `AlignmentGeometry?` | no | `Alignment.center` | Alignment within bounds. |
| filterQuality | `FilterQuality?` | no | `null` | Image layer quality. |
| renderCache | `RenderCache?` | no | `null` | Opt-in frame cache (see `RenderCache`). |

### Return type
`RawLottie`, whose `createRenderObject` returns a `RenderLottie`.
```

--------------------------------

### Basic network load with placeholder

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-builder.md

Loads a Lottie animation from a network URL with a placeholder (CircularProgressIndicator) shown while the composition is null. Uses LottieBuilder.network with width and height constraints.

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

class LoadingAnimation extends StatelessWidget {
  const LoadingAnimation({super.key});

  @override
  Widget build(BuildContext context) {
    return LottieBuilder.network(
      'https://example.com/loader.json',
      width: 100,
      height: 100,
      frameBuilder: (context, child, composition) {
        if (composition == null) {
          return const CircularProgressIndicator();
        }
        return child;
      },
    );
  }
}
```

--------------------------------

### Frame export with progress check

Source: https://github.com/xvrh/lottie-flutter/blob/master/_autodocs/api-reference/lottie-drawable.md

Example function that renders a single frame to a ui.Image using LottieDrawable. It uses setProgress and draw with BoxFit.contain, and notes that setProgress returns true when the frame changes but is ignored here.

```dart
Future<ui.Image> renderFrame(
  LottieComposition composition,
  double progress,
  Size size,
) async {
  final drawable = LottieDrawable(composition);
  final recorder = ui.PictureRecorder();
  final canvas = Canvas(recorder);

  // setProgress returns true when the frame changed; ignore here, we always draw.
  drawable.setProgress(progress);
  drawable.draw(canvas, Offset.zero & size, fit: BoxFit.contain);

  final picture = recorder.endRecording();
  return picture.toImage(size.width.toInt(), size.height.toInt());
}
```

--------------------------------

### Load Telegram Stickers (.tgs) with LottieComposition.decodeGZip

Source: https://github.com/xvrh/lottie-flutter/blob/master/README.md

Loads Telegram Sticker (.tgs) files by providing LottieComposition.decodeGZip as the decoder. Works for both network and asset sources. The example shows a ListView with a network TGS and an asset TGS.

```dart
Widget build(BuildContext context) {
  return ListView(
    children: [
      Lottie.network(
        'https://telegram.org/file/464001484/1/bzi7gr7XRGU.10147/815df2ef527132dd23',
        decoder: LottieComposition.decodeGZip,
      ),
      Lottie.asset(
        'assets/LightningBug_file.tgs',
        decoder: LottieComposition.decodeGZip,
      ),
    ],
  );
}
```
Tokens:
Raw