Getting Started with the React Native Player

In this tutorial, you will install the React Native player and display your first Lottie animation in a React Native or Expo application.

Requirements

React Native >=0.71
iOS 15.4+ / Android API 21+

Installation

npm install @lottiefiles/dotlottie-react-native
# or
yarn add @lottiefiles/dotlottie-react-native

For Expo projects, add the config plugin to your app.json / app.config.js:

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

The Expo plugin automatically sets the iOS deployment target to 15.4 and configures the required Podfile properties.

Then rebuild your native project:

npx expo prebuild

Bare React Native Setup

For non-Expo projects, ensure your iOS Podfile has the minimum deployment target:

platform :ios, '15.4'

Metro Configuration

To use local .lottie files with require(), add 'lottie' to the asset extensions in your metro.config.js:

const { getDefaultConfig } = require('metro-config');

module.exports = (async () => {
  const { resolver: { assetExts } } = await getDefaultConfig();
  return {
    resolver: {
      assetExts: [...assetExts, 'lottie'],
    },
  };
})();

Basic Usage

Load from a URL

import { DotLottie } from '@lottiefiles/dotlottie-react-native';

export default function App() {
  return (
    <DotLottie
      source={{ uri: 'https://lottie.host/example/animation.lottie' }}
      autoplay
      loop
      style={{ width: 300, height: 300 }}
    />
  );
}

Load from a Local Asset

import { DotLottie } from '@lottiefiles/dotlottie-react-native';

export default function App() {
  return (
    <DotLottie
      source={require('./assets/animation.lottie')}
      autoplay
      loop
      style={{ width: 300, height: 300 }}
    />
  );
}

Controlling Playback

Use a ref to access the controller and call playback methods:

import { useRef } from 'react';
import { Button, View } from 'react-native';
import { DotLottie, type Dotlottie } from '@lottiefiles/dotlottie-react-native';

export default function App() {
  const controllerRef = useRef<Dotlottie>(null);

  return (
    <View>
      <DotLottie
        ref={controllerRef}
        source={{ uri: 'https://lottie.host/example/animation.lottie' }}
        loop
        style={{ width: 300, height: 300 }}
      />
      <Button title="Play" onPress={() => controllerRef.current?.play()} />
      <Button title="Pause" onPress={() => controllerRef.current?.pause()} />
      <Button title="Stop" onPress={() => controllerRef.current?.stop()} />
    </View>
  );
}

Listening to Events

<DotLottie
  source={{ uri: 'https://lottie.host/example/animation.lottie' }}
  autoplay
  loop
  style={{ width: 300, height: 300 }}
  onLoad={() => console.log('Loaded')}
  onComplete={() => console.log('Complete')}
  onPlay={() => console.log('Playing')}
  onPause={() => console.log('Paused')}
  onStop={() => console.log('Stopped')}
  onFrame={(frame) => console.log('Frame:', frame)}
  onLoadError={() => console.error('Load error')}
/>

Next Steps

API Reference — Full component props and controller API
Examples — Advanced usage examples