Lottie & dotLottie component for React Native (iOS, Android, and Web)

npm install @lottiefiles/dotlottie-react-native

yarn add @lottiefiles/dotlottie-react-native

To support iOS 15.4, ensure your Podfile specifies the platform version:

platform :ios, '15.4'

After installing the package, navigate to the ios directory and install the pods:

cd ios pod install

To support .lottie files, update your metro.config.js:

// metro.config.js const { getDefaultConfig } = require('metro-config'); module.exports = (async () => { const { resolver: { sourceExts, assetExts }, } = await getDefaultConfig(); return { resolver: { assetExts: [...assetExts, 'lottie'], }, }; })();

Expo projects must include the native binaries before this library can render animations. We ship a config plugin scaffold (withDotLottie) so Expo developers can prepare builds with minimal setup.

1. Add the plugin – the package already declares it under the expo.plugins field, so it is applied automatically. To customize behaviour, you can reference it explicitly in app.json:

   { "expo": { "plugins": ["@lottiefiles/dotlottie-react-native/plugin"] } }

2. Generate native projects – run expo prebuild (or initialise a development build if you haven’t already):

   expo prebuild

3. Create a development build – install the native code with expo run:ios / expo run:android, or your preferred EAS build workflow. Expo Go does not bundle the DotLottie native module.

Tip: this repository ships an Expo dev-client harness under expo-example/. Use it to exercise the config plugin locally with yarn workspace dotlottie-react-native-expo-example prebuild.

If you must stay in Expo Go, fall back to the web implementation shipped in this package (or the underlying @lottiefiles/dotlottie-react) until a native build is available:

import { Platform } from 'react-native'; import { DotLottie as DotLottieNative } from '@lottiefiles/dotlottie-react-native'; import { DotLottie as DotLottieWeb } from '@lottiefiles/dotlottie-react'; export const DotLottie = Platform.select({ ios: DotLottieNative, android: DotLottieNative, default: DotLottieWeb, });

This keeps the API surface consistent while you work entirely in Expo Go. Once you produce a dev build, swap back to the native export everywhere or gate the fallback behind feature flags.

This package supports React Native Web out of the box. The web implementation uses @lottiefiles/dotlottie-react under the hood.

@lottiefiles/dotlottie-react-native now ships with a Legacy Interop bridge so the same component works on both Paper and Fabric. Paper remains the default on every platform, and you can opt-in to the new architecture per-app.

• iOS: enable Fabric by turning on RCT_NEW_ARCH_ENABLED before running pod install. For example:

  cd ios RCT_NEW_ARCH_ENABLED=1 bundle exec pod install

  Clearing the flag (or setting it to 0) keeps the Paper manager in place. No changes are required to continue using Paper.

• Android: toggle the architecture by setting newArchEnabled=true in android/gradle.properties, or pass -PnewArchEnabled=true/false (or ORG_GRADLE_PROJECT_newArchEnabled=...) on the Gradle command line.

The repository’s example app exposes Yarn scripts to exercise each mode:

yarn ios:paper # Paper build yarn ios:fabric # Fabric build yarn android:paper # Paper build yarn android:fabric # Fabric build

Use the matching :build variants (for example, yarn ios:fabric:build) when you only need to compile instead of launching the simulator/emulator.

import { Button, StyleSheet, View } from 'react-native'; import { DotLottie, Mode, type Dotlottie } from '@lottiefiles/dotlottie-react-native'; import { useRef } from 'react'; export default function App() { const ref = useRef<Dotlottie>(null); return ( <View style={styles.container}> <DotLottie ref={ref} source={require('../assets/animation.lottie')} style={styles.box} loop={false} autoplay={false} /> <Button title="Play" onPress={() => ref.current?.play()} /> <Button title="Pause" onPress={() => ref.current?.pause()} /> <Button title="Stop" onPress={() => ref.current?.stop()} /> <Button title="Loop" onPress={() => ref.current?.setLoop(true)} /> <Button title="Speed" onPress={() => ref.current?.setSpeed(1)} /> <Button title="FORWARD" onPress={() => ref.current?.setPlayMode(Mode.FORWARD)} /> <Button title="REVERSE" onPress={() => ref.current?.setPlayMode(Mode.REVERSE)} /> </View> ); } const styles = StyleSheet.create({ container: { flex: 1, alignItems: 'center', justifyContent: 'center', }, box: { width: 200, height: 200, marginVertical: 20, }, });

Access these methods via a ref:

const ref = useRef<Dotlottie>(null); ref.current?.play();

See the contributing guide to learn how to contribute to the repository and the development workflow.

MIT

Made with create-react-native-library