|
| 1 | +--- |
| 2 | +id: getting-started |
| 3 | +title: Getting started |
| 4 | +slug: / |
| 5 | +--- |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +Lightweight declarative animations powered by platform APIs. Uses Core Animation on iOS and Animator on Android — zero JS overhead. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +```bash |
| 14 | +npm install react-native-ease |
| 15 | +# or |
| 16 | +yarn add react-native-ease |
| 17 | +``` |
| 18 | + |
| 19 | +## Example |
| 20 | + |
| 21 | +```tsx |
| 22 | +import { EaseView } from 'react-native-ease'; |
| 23 | + |
| 24 | +function FadeCard({ visible, children }) { |
| 25 | + return ( |
| 26 | + <EaseView |
| 27 | + animate={{ opacity: visible ? 1 : 0 }} |
| 28 | + transition={{ type: 'timing', duration: 300 }} |
| 29 | + style={styles.card} |
| 30 | + > |
| 31 | + {children} |
| 32 | + </EaseView> |
| 33 | + ); |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +`EaseView` works like a regular `View` — it accepts children, styles, and all standard view props. When values in `animate` change, it smoothly transitions to the new values using native platform animations. |
| 38 | + |
| 39 | +## Why Ease |
| 40 | + |
| 41 | +### Goals |
| 42 | + |
| 43 | +- **Fast** — Animations run entirely on native platform APIs (CAAnimation, ObjectAnimator/SpringAnimation). No JS animation loop, no worklets, no shared values. |
| 44 | +- **Simple** — CSS-transition-like API. Set target values, get smooth animations. One component, a few props. |
| 45 | +- **Lightweight** — Minimal native code, no C++ runtime, no custom animation engine. Just a thin declarative wrapper around what the OS already provides. |
| 46 | +- **Interruptible** — Changing values mid-animation smoothly redirects to the new target. No jumps. |
| 47 | + |
| 48 | +### Non-goals |
| 49 | + |
| 50 | +- **Complex gesture-driven animations** — If you need pan/pinch-driven animations, animation worklets, or shared values across components, use [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated). |
| 51 | +- **Layout animations** — Animating width/height/layout changes is not supported. |
| 52 | +- **Shared element transitions** — Use Reanimated or React Navigation's shared element transitions. |
| 53 | +- **Old architecture** — Fabric (new architecture) only. |
| 54 | + |
| 55 | +## When to use this vs Reanimated |
| 56 | + |
| 57 | +| Use case | Ease | Reanimated | |
| 58 | +| -------------------------------------- | ---- | ---------- | |
| 59 | +| Fade/slide/scale on state change | ✅ | | |
| 60 | +| Enter/exit animations | ✅ | | |
| 61 | +| Gesture-driven animations (pan, pinch) | | ✅ | |
| 62 | +| Layout animations (width, height) | | ✅ | |
| 63 | +| Complex interpolations & chaining | | ✅ | |
| 64 | + |
| 65 | +## Styling integrations |
| 66 | + |
| 67 | +### NativeWind support |
| 68 | + |
| 69 | +If you're using [NativeWind](https://www.nativewind.dev/) (v4+), add this import once in your app's entry point (for example `_layout.tsx` or `App.tsx`): |
| 70 | + |
| 71 | +```tsx |
| 72 | +import 'react-native-ease/nativewind'; |
| 73 | +``` |
| 74 | + |
| 75 | +This registers `EaseView` with NativeWind's `cssInterop` so `className` is properly converted to styles: |
| 76 | + |
| 77 | +```tsx |
| 78 | +<EaseView |
| 79 | + className="flex-1 bg-white rounded-2xl p-4" |
| 80 | + animate={{ opacity: visible ? 1 : 0 }} |
| 81 | + transition={{ type: 'timing', duration: 300 }} |
| 82 | +> |
| 83 | + {children} |
| 84 | +</EaseView> |
| 85 | +``` |
| 86 | + |
| 87 | +### Uniwind support |
| 88 | + |
| 89 | +If you're using [Uniwind](https://docs.uniwind.dev/), first follow the [Uniwind quickstart](https://docs.uniwind.dev/quickstart) to install and configure Uniwind in your app. |
| 90 | + |
| 91 | +Once Uniwind is set up, import `EaseView` from the Uniwind entry point: |
| 92 | + |
| 93 | +```tsx |
| 94 | +import { EaseView } from 'react-native-ease/uniwind'; |
| 95 | +``` |
| 96 | + |
| 97 | +```tsx |
| 98 | +<EaseView |
| 99 | + className="flex-1 bg-white rounded-2xl p-4" |
| 100 | + animate={{ opacity: visible ? 1 : 0 }} |
| 101 | + transition={{ type: 'timing', duration: 300 }} |
| 102 | +> |
| 103 | + {children} |
| 104 | +</EaseView> |
| 105 | +``` |
| 106 | + |
| 107 | +## Migration skill |
| 108 | + |
| 109 | +If you're already using `react-native-reanimated` or React Native's `Animated` API, this project includes an [Agent Skill](https://agentskills.io) that scans your codebase for animations that can be replaced with `react-native-ease` and migrates them automatically. |
| 110 | + |
| 111 | +```bash |
| 112 | +npx skills add appandflow/react-native-ease |
| 113 | +``` |
| 114 | + |
| 115 | +Then invoke the skill in your agent (for example `/react-native-ease-refactor` in Claude Code). |
0 commit comments