# dotLottie React Native Player API Reference API reference for the dotLottie React Native player. Details for the DotLottie component props, Dotlottie ref methods, types, enums, and all supported events. # dotLottie React Native Player API Reference ## DotLottie Component Props ### Animation Source | Prop | Type | Description | | -------- | ------------------------------------- | ------------------------------------------------------------------ | | `source` | `string \| number \| { uri: string }` | Animation source: a URI string, a `require()` asset, or `{ uri }`. | ### Playback | Prop | Type | Default | Description | | ----------------------- | -------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------- | | `autoplay` | `boolean` | `false` | Auto-starts the animation on load. | | `loop` | `boolean` | `false` | Whether the animation loops. | | `speed` | `number` | `1` | Playback speed multiplier. | | `playMode` | `Mode.FORWARD \| Mode.REVERSE \| Mode.BOUNCE \| Mode.REVERSE_BOUNCE` | `Mode.FORWARD` | Playback direction mode. | | `segment` | `[number, number]` | `undefined` | Frame range to play as `[startFrame, endFrame]`. | | `marker` | `string` | `undefined` | Named marker to play. | | `useFrameInterpolation` | `boolean` | `undefined` | Enable subframe interpolation. Actual default depends on the native renderer. | ### Rendering | Prop | Type | Default | Description | | ---------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------- | | `renderer` | `'sw' \| 'gl'` | `'sw'` | Rendering backend. `'sw'` = software renderer, `'gl'` = OpenGL ES renderer. Android GL support added in v0.8.0. | ### Theming | Prop | Type | Default | Description | | --------- | -------- | ----------- | ------------------------------------------------- | | `themeId` | `string` | `undefined` | ID of the theme to apply from the `.lottie` file. | ### State Machines | Prop | Type | Default | Description | | ---------------- | -------- | ----------- | ---------------------------------------------------------------- | | `stateMachineId` | `string` | `undefined` | ID of the state machine to load automatically on animation load. | ### Style | Prop | Type | Description | | ------- | ----------- | ------------------------------------ | | `style` | `ViewStyle` | Style applied to the animation view. | ### Event Callbacks #### Animation Events | Prop | Signature | Description | | ------------- | ----------------------------- | ------------------------------------- | | `onLoad` | `() => void` | Fired when the animation is loaded. | | `onComplete` | `() => void` | Fired when playback completes. | | `onLoadError` | `() => void` | Fired when loading fails. | | `onPlay` | `() => void` | Fired when playback starts. | | `onPause` | `() => void` | Fired when playback pauses. | | `onStop` | `() => void` | Fired when playback stops. | | `onFrame` | `(frame: number) => void` | Fired on each frame update. | | `onRender` | `(frame: number) => void` | Fired when a new frame is rendered. | | `onLoop` | `(loopCount: number) => void` | Fired when a loop completes. | | `onFreeze` | `() => void` | Fired when the animation is frozen. | | `onUnFreeze` | `() => void` | Fired when the animation is unfrozen. | | `onDestroy` | `() => void` | Fired when the player is destroyed. | #### State Machine Events | Prop | Signature | Description | | ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------------- | | `onStateMachineStart` | `() => void` | Fired when the state machine starts. | | `onStateMachineStop` | `() => void` | Fired when the state machine stops. | | `onStateMachineStateEntered` | `(state: string) => void` | Fired when entering a state. | | `onStateMachineStateExit` | `(state: string) => void` | Fired when exiting a state. | | `onStateMachineTransition` | `(from: string, to: string) => void` | Fired on a state transition. | | `onStateMachineCustomEvent` | `(event: string) => void` | Fired on a custom state machine event. | | `onStateMachineError` | `(error: string) => void` | Fired when the state machine encounters an error. | | `onStateMachineInputFired` | `(inputName: string) => void` | Fired when an input fires. | | `onStateMachineBooleanInputChange` | `(name: string, oldVal: boolean, newVal: boolean) => void` | Fired when a boolean input changes. | | `onStateMachineNumericInputChange` | `(name: string, oldVal: number, newVal: number) => void` | Fired when a numeric input changes. | | `onStateMachineStringInputChange` | `(name: string, oldVal: string, newVal: string) => void` | Fired when a string input changes. | --- ## Ref Methods (`Dotlottie`) Attach a `ref` to the `DotLottie` component to access the controller. The ref type is `Dotlottie`: ```tsx import { DotLottie, type Dotlottie } from "@lottiefiles/dotlottie-react-native"; const controllerRef = useRef(null); ``` ### Playback Methods | Method | Description | | ---------------------------------------- | --------------------------------------------- | | `play()` | Starts or resumes playback. | | `pause()` | Pauses playback. | | `stop()` | Stops playback and resets to the first frame. | | `setFrame(frame: number)` | Jumps to the specified frame. | | `setSpeed(speed: number)` | Sets the playback speed multiplier. | | `setLoop(loop: boolean)` | Enables or disables looping. | | `setPlayMode(mode: Mode)` | Sets the playback mode. | | `setSegment(start: number, end: number)` | Sets the frame range to play. | | `setMarker(marker: string)` | Sets the named marker to play. | | `freeze()` | Freezes the animation at the current frame. | | `unfreeze()` | Unfreezes the animation. | | `resize(width: number, height: number)` | Resizes the animation view. | ### State Queries (Async) | Method | Return Type | Description | | --------------------- | ------------------ | ------------------------------------------------- | | `isPlaying()` | `Promise` | Returns `true` if currently playing. | | `isPaused()` | `Promise` | Returns `true` if paused. | | `isStopped()` | `Promise` | Returns `true` if stopped. | | `isLoaded()` | `Promise` | Returns `true` if the animation is loaded. | | `currentFrame()` | `Promise` | Returns the current frame number. | | `totalFrames()` | `Promise` | Returns the total number of frames. | | `duration()` | `Promise` | Returns the animation duration in milliseconds. | | `speed()` | `Promise` | Returns the current playback speed. | | `loopCount()` | `Promise` | Returns the current loop iteration count. | | `activeThemeId()` | `Promise` | Returns the ID of the currently active theme. | | `activeAnimationId()` | `Promise` | Returns the ID of the currently active animation. | ### Animation & Theme | Method | Description | | ------------------------------------ | ------------------------------------------------------------- | | `loadAnimation(animationId: string)` | Loads a specific animation by ID from a multi-animation file. | | `setTheme(themeId: string)` | Applies a theme by ID. | ### State Machine | Method | Description | | ---------------------------------------------------------- | ----------------------------------------------------------- | | `stateMachineLoad(stateMachineId: string)` | Loads a state machine by ID. | | `stateMachineStart()` | Starts the loaded state machine. | | `stateMachineStop()` | Stops the state machine. | | `stateMachineFire(event: string)` | Fires a named event to the state machine. | | `stateMachineSetBooleanInput(key: string, value: boolean)` | Sets a boolean input. Returns `boolean` indicating success. | | `stateMachineSetNumericInput(key: string, value: number)` | Sets a numeric input. Returns `boolean` indicating success. | | `stateMachineSetStringInput(key: string, value: string)` | Sets a string input. Returns `boolean` indicating success. | --- ## Types & Enums ### `Dotlottie` The ref type for the `DotLottie` component controller. Import it as: ```tsx import { type Dotlottie } from "@lottiefiles/dotlottie-react-native"; ``` ### `Renderer` ```tsx import { type Renderer } from "@lottiefiles/dotlottie-react-native"; type Renderer = "sw" | "gl"; ``` - `'sw'` — Software renderer (default) - `'gl'` — OpenGL ES renderer (Android GL support added in v0.8.0) ### `Mode` ```tsx import { Mode } from "@lottiefiles/dotlottie-react-native"; enum Mode { FORWARD = 0, REVERSE = 1, BOUNCE = 2, REVERSE_BOUNCE = 3, } ``` --- ## Platform Differences (Web) The package includes a web implementation that wraps `@lottiefiles/dotlottie-react`. The following features are **not available** on web: - `setTheme()` — use `loadTheme()` instead on web - `stateMachineLoad()` — use `loadStateMachine()` instead on web - `stateMachineFire()` — not supported on web - `stateMachineSetBooleanInput()`, `stateMachineSetNumericInput()`, `stateMachineSetStringInput()` — not supported on web - `resize()` — ignores width/height parameters on web - `onDestroy` event — not wired on web - State machine event callbacks (`onStateMachine*`) — not supported on web --- ## Related Topics - [Getting Started](/en/runtimes/distributions/react-native/v0.x/getting-started) - [Examples](/en/runtimes/distributions/react-native/v0.x/examples)