Lottie: Introduce onAnimationData() callback

packages/docs/docs/lottie/lottie-comp.md

@@ -31,6 +31,10 @@ export const MyAnimation: React.FC = () => {
 
 A JSON object that adheres to the Lottie schema.
 
+:::note
+If the identity of the object changes, the animation will be re-initialized. Consider memoizing the animationData value.
+:::
+
 ### `className`
 
 A CSS class name to be given to the `<div>` that contains the animation.
@@ -56,3 +60,39 @@ The speed of the animation. A higher number is faster. Default: `1`.
 ### `style`
 
 CSS properties to be applied to the `<div>` that contains the animation.
+
+### `onAnimationLoaded`
+
+_available from v3.2.29, optional_
+
+Callback that gets invoked when the Lottie animation has been initialized. The Lottie [`AnimationItem`](https://airbnb.io/lottie/#/web?id=usage-1) gets passed as a parameter.
+
+```tsx twoslash
+import type { LottieAnimationData } from "@remotion/lottie";
+
+const animationData: LottieAnimationData = {
+  fr: 0,
+  w: 0,
+  h: 0,
+  op: 0,
+};
+
+// ---cut---
+
+import { Lottie } from "@remotion/lottie";
+import { AnimationItem } from "lottie-web";
+import { useCallback } from "react";
+
+const Comp: React.FC = () => {
+  const onAnimationLoaded = useCallback((item: AnimationItem) => {
+    console.log(item.renderer);
+  }, []);
+
+  return (
+    <Lottie
+      animationData={animationData}
+      onAnimationLoaded={onAnimationLoaded}
+    />
+  );
+};
+```

packages/example/src/Lottie/Loader/index.tsx

@@ -1,5 +1,6 @@
 import {getLottieMetadata, Lottie, LottieAnimationData} from '@remotion/lottie';
-import {useEffect, useState} from 'react';
+import {AnimationItem} from 'lottie-web';
+import {useCallback, useEffect, useState} from 'react';
 import {
 	continueRender,
 	delayRender,
@@ -27,6 +28,10 @@ const LottieLoader = () => {
 			});
 	}, [handle]);
 
+	const onAnimationLoaded = useCallback((item: AnimationItem) => {
+		console.log(item.renderer);
+	}, []);
+
 	if (!animationData) {
 		return null;
 	}
@@ -35,7 +40,14 @@ const LottieLoader = () => {
 	const nLoop = df && frame > 0 ? Math.ceil(frame / df) : 1;
 	const direction = nLoop % 2 === 0 ? 'backward' : 'forward';
 
-	return <Lottie loop animationData={animationData} direction={direction} />;
+	return (
+		<Lottie
+			loop
+			animationData={animationData}
+			direction={direction}
+			onAnimationLoaded={onAnimationLoaded}
+		/>
+	);
 };
 
 export default LottieLoader;

packages/lottie/src/Lottie.tsx

@@ -14,6 +14,7 @@ export const Lottie = ({
 	loop,
 	playbackRate,
 	style,
+	onAnimationLoaded,
 }: LottieProps) => {
 	if (typeof animationData !== 'object') {
 		throw new Error(
@@ -27,6 +28,10 @@ export const Lottie = ({
 	const animationRef = useRef<AnimationItem>();
 	const lastFrameRef = useRef<number | null>(null);
 	const containerRef = useRef<HTMLDivElement>(null);
+
+	const onAnimationLoadedRef = useRef<LottieProps['onAnimationLoaded']>();
+	onAnimationLoadedRef.current = onAnimationLoaded;
+
 	const [handle] = useState(() =>
 		delayRender('Waiting for Lottie animation to load')
 	);
@@ -54,6 +59,8 @@ export const Lottie = ({
 
 		animation.addEventListener('DOMLoaded', onComplete);
 
+		onAnimationLoadedRef.current?.(animation);
+
 		return () => {
 			lastFrameRef.current = animation.currentFrame;
 			animation.removeEventListener('DOMLoaded', onComplete);

packages/lottie/src/types.ts

@@ -1,3 +1,4 @@
+import type {AnimationItem} from 'lottie-web';
 import type {CSSProperties} from 'react';
 
 export type LottieAnimationData = {
@@ -32,4 +33,8 @@ export type LottieProps = {
 	 * CSS properties to apply to the container of the animation.
 	 */
 	style?: CSSProperties;
+	/**
+	 * Callback that gets invoked when new animation data has been initialized
+	 */
+	onAnimationLoaded?: (animation: AnimationItem) => void;
 };