@jayming/expo-svga-player

Lightweight Expo / React Native wrapper for SVGA animations (Android, iOS, Web).

This repository contains a small native module exposing a SvgaPlayer view component with a unified API across platforms.

Installation

Install the package in your project (example uses pnpm in the repository root for the example app):

# Using npm
npm install @jayming/expo-svga-player

# Using pnpm
pnpm add @jayming/expo-svga-player

If you are developing with a bare React Native project, ensure expo packages are configured (see Expo docs). For iOS, run:

npx pod-install

Usage (React / React Native)

Simple example:

import SvgaPlayer from "@jayming/expo-svga-player";

// In JSX
<SvgaPlayer
  source="https://example.com/anim.svga"
  autoPlay={true}
  loops={0} // 0 means infinite in the JS API
  clearsAfterStop={true}
  align="center" // "top" | "center" | "bottom"
  style={{ width: 320, height: 420 }}
  onLoaded={() => console.log("loaded")}
  onFinished={() => console.log("finished")}
/>;

You can call startAnimation() / stopAnimation() using a ref to the view.

Platform notes & gotchas

• Loops semantics:

  • On JS side loops is a number where 0 means infinite looping. Android native SVGA implementations sometimes treat 0 specially, so the Android bridge maps 0 to a very large repeat count to emulate infinite looping.

• Align behavior (vertical alignment):

  • align accepts "top" | "center" | "bottom" and maps to platform-appropriate alignment.
  • Web: the container uses flexbox justify-content mapping so the canvas aligns vertically.
  • Android: align maps to ImageView.ScaleType plus enabling adjustViewBounds and requesting a layout pass to better reflect top/center/bottom. If you still see horizontal alignment, the parent layout may enforce constraints — try adjusting parent sizing or use a fixed height on the player view.

• Threading / playback start:

  • Native parsing may run on background threads; the module ensures UI operations (setting the video item and starting playback) are posted to the UI thread to avoid silent failures.

Debugging

• If animation does not appear on Android:
  1. Confirm onLoaded event fires (the component emits onLoaded when parsing completes).
  2. Check adb logcat for logs containing SvgaPlayerView or SVGA.

Example logcat filter:

adb logcat | grep SvgaPlayerView

Example app

The example/ folder contains a small React Native app demonstrating usage and runtime controls for loops, align, and manual URL input. Run it from the example directory:

cd example
pnpm install
pnpm android

Contributing

Contributions welcome — please open issues or PRs. Keep changes focused and include platform-specific testing steps when touching native code.

License

See the project root for license information.