Skip to main content

Introduction

Inertia (@onlynative/inertia) is a thin, ergonomic wrapper around react-native-reanimated. Animations are expressed as props on a component — no shared values, no worklets, no useAnimatedStyle boilerplate. The vocabulary takes cues from Framer Motion (web) and react-spring (cross-platform).

Status: 0.0.1-alpha. The full v0.1 surface is implemented and exercised by the example app — primitives, per-property transitions, sequences, variants, gestures, <Presence>, decay, <MotionConfig>, and the value-layer hooks. APIs may still shift before 0.1.0; see the roadmap for graduation gates.

What you get​

  • DX-first. Animations are props on a component, not imperative shared values, worklets, and useAnimatedStyle boilerplate.
  • Per-primitive style inference. Motion.View accepts ViewStyle keys, Motion.Text accepts TextStyle, Motion.Image accepts ImageStyle. No shared union fallback that lets wrong props slip through.
  • react-spring vocabulary. Spring config uses tension, friction, mass, velocity. Reanimated's raw stiffness / damping never appear in the public surface.
  • One gesture prop on every primitive. pressed, focused, focusVisible (keyboard focus only — W3C :focus-visible), hovered (web) sub-states; no whileTap / whilePress soup, no separate "pressable" variant.
  • Per-primitive tree-shaking. Subpath imports (@onlynative/inertia/view, /text, /image, /pressable, /scroll-view) so apps that animate one element don't ship the whole library.
  • Stable worklets. The factory hashes resolved animate / transition objects and memoizes the generated worklet + useAnimatedStyle — re-renders with unchanged values produce zero new UI-thread closures.

Install​

Pick your package manager — Yarn is the default. The selection syncs across every install snippet in the docs.

yarn add @onlynative/inertia react-native-reanimated

Then enable the Reanimated Babel plugin per its install guide.

A first animation​

import { Motion } from '@onlynative/inertia'

export function FadeIn() {
  return (
    <Motion.View
      initial={{ opacity: 0, translateY: 20 }}
      animate={{ opacity: 1, translateY: 0 }}
      transition={{
        opacity: { type: 'timing', duration: 200 },
        translateY: { type: 'spring', tension: 180, friction: 12 },
      }}
    />
  )
}

For tree-shaking when only one primitive is used:

import { MotionView } from '@onlynative/inertia/view'

Runnable example​

The full example app is embedded below — every primitive, every gesture, the same code that ships under example/ in the repo. Tap a screen and interact:

example

Each docs page deep-links into the relevant screen of this same app, so you can try the API as you read.

Where to next​

  • Installation — install + Reanimated Babel plugin.
  • Primitives — Motion.View / Text / Image / Pressable / ScrollView.
  • Transitions — spring (default) / timing / decay / no-animation.
  • Sequences & repeat — keyframe arrays and the unified repeat shape.
  • Variants — named animation states + useVariants controller.
  • Gestures — pressed / focused / focusVisible / hovered sub-states.
  • Gestures adapter — drag / pan / swipe via react-native-gesture-handler (optional package).
  • Gradients — animatable MotionLinearGradient via expo-linear-gradient (optional package).
  • SVG — animatable MotionPath via react-native-svg (optional package).
  • Presence — mount / unmount transitions.
  • Layout — auto-layout transitions on position + size changes.
  • MotionConfig — reduce-motion gate.
  • Hooks and createMotionComponent — escape hatches.