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:

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

const controllerRef = useRef<Dotlottie>(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<boolean>`	Returns `true` if currently playing.
`isPaused()`	`Promise<boolean>`	Returns `true` if paused.
`isStopped()`	`Promise<boolean>`	Returns `true` if stopped.
`isLoaded()`	`Promise<boolean>`	Returns `true` if the animation is loaded.
`currentFrame()`	`Promise<number>`	Returns the current frame number.
`totalFrames()`	`Promise<number>`	Returns the total number of frames.
`duration()`	`Promise<number>`	Returns the animation duration in milliseconds.
`speed()`	`Promise<number>`	Returns the current playback speed.
`loopCount()`	`Promise<number>`	Returns the current loop iteration count.
`activeThemeId()`	`Promise<string>`	Returns the ID of the currently active theme.
`activeAnimationId()`	`Promise<string>`	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:

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

`Renderer`

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`

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

dotLottie React Native Player API Reference

dotLottie React Native Player API Reference

DotLottie Component Props

Animation Source

Playback

Rendering

Theming

State Machines

Style

Event Callbacks

Animation Events

State Machine Events

Ref Methods (Dotlottie)

Playback Methods

State Queries (Async)

Animation & Theme

State Machine

Types & Enums

Dotlottie

Renderer

Mode

Platform Differences (Web)

Related Topics

Ref Methods (`Dotlottie`)

`Dotlottie`

`Renderer`

`Mode`