Skip to content
Back to search

react-native-ease-plugins

MarketplaceWorks with Claude CodeGitHub

πŸƒ Lightweight declarative animations powered by platform APIs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/appandflow/react-native-ease with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/appandflow/react-native-ease'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/appandflow-react-native-ease/badge.svg)](/listings/appandflow-react-native-ease)

HTML

<a href="/listings/appandflow-react-native-ease"><img src="/api/listings/appandflow-react-native-ease/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installation

npm install react-native-ease
# or
yarn add react-native-ease

Migration Skill

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.

npx skills add appandflow/react-native-ease

Then invoke the skill in your agent (e.g., `/react-native-ease-refactor` in Claude Code).

The skill will:

1. Scan your project for Reanimated/Animated code 2. Classify which animations can be migrated (and which can't, with reasons) 3. Show a migration report with before/after details 4. Let you select which components to migrate 5. Apply the changes, preserving all non-animation logic

NativeWind Support

If you're using [NativeWind](https://www.nativewind.dev/) (v4+), add this import once in your app's entry point (e.g., `_layout.tsx` or `App.tsx`):

import 'react-native-ease/nativewind';

This registers `EaseView` with NativeWind's `cssInterop` so `className` is properly converted to styles:

<EaseView
  className="flex-1 bg-white rounded-2xl p-4"
  animate={{ opacity: visible ? 1 : 0 }}
  transition={{ type: 'timing', duration: 300 }}
>
  {children}
</EaseView>

> **Tip:** If you use the [migration skill](#migration-skill), it detects NativeWind automatically and adds this import for you.

Uniwind Support

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. That setup includes the required CSS entry file, app-root CSS import, and bundler configuration.

Once Uniwind is set up, import `EaseView` from the Uniwind entry point:

import { EaseView } from 'react-native-ease/uniwind';

This wraps `EaseView` with Uniwind's `withUniwind(...)` so `className` is converted to styles:

<EaseView
  className="flex-1 bg-white rounded-2xl p-4"
  animate={{ opacity: visible ? 1 : 0 }}
  transition={{ type: 'timing', duration: 300 }}
>
  {children}
</EaseView>

Example

import { EaseView } from 'react-native-ease';

function FadeCard({ visible, children }) {
  return (
    <EaseView
      animate={{ opacity: visible ? 1 : 0 }}
      transition={{ type: 'timing', duration: 300 }}
      style={styles.card}
    >
      {children}
    </EaseView>
  );
}

`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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "react-native-ease-plugins",
  3. "owner": {
  4. "name": "AppAndFlow",
  5. "email": "devops@appandflow.com"
  6. },
  7. "metadata": {
  8. "description": "Claude Code skills for react-native-ease β€” migrate Reanimated/Animated code to react-native-ease"
  9. },
  10. "plugins": [
  11. {
  12. "name": "react-native-ease",
  13. "source": "./",
  14. "description": "Scan for Animated/Reanimated code and migrate to react-native-ease",
  15. "version": "0.2.0",
  16. "author": {
  17. "name": "AppAndFlow"
  18. }
  19. }
  20. ]
  21. }
README.md Β· README Β· 759 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <img width="100%" height="auto" alt="Native Animations with React Native Ease, maintained by App & Flow" src="docs/static/img/github-banner.png" />
  2. Lightweight declarative animations powered by platform APIs. Uses Core Animation on iOS and Animator on Android β€” zero JS overhead.
  3. ## About
  4. App & Flow is a Montreal-based React Native engineering and consulting studio. We partner with the world’s top companies and are recommended by [Expo](https://expo.dev/consultants). Need a hand? Let’s build together. team@appandflow.com
  5. Visit the [React Native Ease website](https://rne.appandflow.com).
  6. ## Demo
  7. ![ease-demo](https://github.com/user-attachments/assets/09658b07-803e-4b7e-a23c-831a6c63df84)
  8. ## Getting started
  9. ### Installation
  10. ```bash
  11. npm install react-native-ease
  12. # or
  13. yarn add react-native-ease
  14. ```
  15. ### Swift Package Manager (iOS)
  16. The package includes a `Package.swift` for apps that use Swift Package Manager instead of CocoaPods (React Native 0.88 or newer). An app moves to Swift Package Manager with `npx react-native spm add`. After that, React Native links this package automatically, and no extra step is needed.
  17. The Swift Package Manager setup supports iOS only. On tvOS, use CocoaPods.
  18. ### Migration Skill
  19. 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.
  20. ```bash
  21. npx skills add appandflow/react-native-ease
  22. ```
  23. Then invoke the skill in your agent (e.g., `/react-native-ease-refactor` in Claude Code).
  24. The skill will:
  25. 1. Scan your project for Reanimated/Animated code
  26. 2. Classify which animations can be migrated (and which can't, with reasons)
  27. 3. Show a migration report with before/after details
  28. 4. Let you select which components to migrate
  29. 5. Apply the changes, preserving all non-animation logic
  30. ### NativeWind Support
  31. If you're using [NativeWind](https://www.nativewind.dev/) (v4+), add this import once in your app's entry point (e.g., `_layout.tsx` or `App.tsx`):
  32. ```tsx
  33. import 'react-native-ease/nativewind';
  34. ```
  35. This registers `EaseView` with NativeWind's `cssInterop` so `className` is properly converted to styles:
  36. ```tsx
  37. <EaseView
  38. className="flex-1 bg-white rounded-2xl p-4"
  39. animate={{ opacity: visible ? 1 : 0 }}
  40. transition={{ type: 'timing', duration: 300 }}
  41. >
  42. {children}
  43. </EaseView>
  44. ```
  45. > **Tip:** If you use the [migration skill](#migration-skill), it detects NativeWind automatically and adds this import for you.
  46. ### Uniwind Support
  47. If you're using [Uniwind](https://docs.uniwind.dev/), first follow the
  48. [Uniwind quickstart](https://docs.uniwind.dev/quickstart) to install and
  49. configure Uniwind in your app. That setup includes the required CSS entry file,
  50. app-root CSS import, and bundler configuration.
  51. Once Uniwind is set up, import `EaseView` from the Uniwind entry point:
  52. ```tsx
  53. import { EaseView } from 'react-native-ease/uniwind';
  54. ```
  55. This wraps `EaseView` with Uniwind's `withUniwind(...)` so `className` is converted to styles:
  56. ```tsx
  57. <EaseView
  58. className="flex-1 bg-white rounded-2xl p-4"
  59. animate={{ opacity: visible ? 1 : 0 }}
  60. transition={{ type: 'timing', duration: 300 }}
  61. >
  62. {children}
  63. </EaseView>
  64. ```
  65. ### Example
  66. ```tsx
  67. import { EaseView } from 'react-native-ease';
  68. function FadeCard({ visible, children }) {
  69. return (
  70. <EaseView
  71. animate={{ opacity: visible ? 1 : 0 }}
  72. transition={{ type: 'timing', duration: 300 }}
  73. style={styles.card}
  74. >
  75. {children}
  76. </EaseView>
  77. );
  78. }
  79. ```
  80. `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.
  81. ## Why
  82. ### Goals
  83. - **Fast** β€” Animations run entirely on native platform APIs (CAAnimation, ObjectAnimator/SpringAnimation). No JS animation loop, no worklets, no shared values.
  84. - **Simple** β€” CSS-transition-like API. Set target values, get smooth animations. One component, a few props.
  85. - **Lightweight** β€” Minimal native code, no C++ runtime, no custom animation engine. Just a thin declarative wrapper around what the OS already provides.
  86. - **Interruptible** β€” Changing values mid-animation smoothly redirects to the new target. No jumps.
  87. ### Non-Goals
  88. - **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).
  89. - **Layout animations** β€” Animating width/height/layout changes is not supported.
  90. - **Shared element transitions** β€” Use Reanimated or React Navigation's shared element transitions.
  91. - **Old architecture** β€” Fabric (new architecture) only.
  92. ### When to use this vs Reanimated
  93. | Use case | Ease | Reanimated |
  94. | -------------------------------------- | ---- | ---------- |
  95. | Fade/slide/scale on state change | βœ… | |
  96. | Enter/exit animations | βœ… | |
  97. | Gesture-driven animations (pan, pinch) | | βœ… |
  98. | Layout animations (width, height) | | βœ… |
  99. | Complex interpolations & chaining | | βœ… |
  100. ## Guide
  101. ### Timing Animations
  102. Timing animations transition from one value to another over a fixed duration with an easing curve.
  103. ```tsx
  104. <EaseView
  105. animate={{ opacity: isVisible ? 1 : 0 }}
  106. transition={{ type: 'timing', duration: 300, easing: 'easeOut' }}
  107. />
  108. ```
  109. | Parameter | Type | Default | Description |
  110. | ---------- | ------------ | ------------- | ------------------------------------------------------------------------ |
  111. | `duration` | `number` | `300` | Duration in milliseconds |
  112. | `easing` | `EasingType` | `'easeInOut'` | Easing curve (preset name or `[x1, y1, x2, y2]` cubic bezier) |
  113. | `delay` | `number` | `0` | Delay in milliseconds before the animation starts |
  114. | `loop` | `string` | β€” | `'repeat'` restarts from the beginning, `'reverse'` alternates direction |
  115. Available easing curves:
  116. - `'linear'` β€” constant speed
  117. - `'easeIn'` β€” starts slow, accelerates
  118. - `'easeOut'` β€” starts fast, decelerates
  119. - `'easeInOut'` β€” slow start and end, fast middle
  120. - `[x1, y1, x2, y2]` β€” custom cubic bezier (same as CSS `cubic-bezier()`)
  121. ### Custom Easing
  122. Pass a `[x1, y1, x2, y2]` tuple for custom cubic bezier curves. The values correspond to the two control points of the bezier curve, matching the CSS `cubic-bezier()` function.
  123. ```tsx
  124. // Standard Material Design easing
  125. <EaseView
  126. animate={{ opacity: isVisible ? 1 : 0 }}
  127. transition={{ type: 'timing', duration: 300, easing: [0.4, 0, 0.2, 1] }}
  128. />
  129. // Overshoot (y-values can exceed 0–1)
  130. <EaseView
  131. animate={{ scale: active ? 1.2 : 1 }}
  132. transition={{ type: 'timing', duration: 500, easing: [0.68, -0.55, 0.265, 1.55] }}
  133. />
  134. ```
  135. x-values (x1, x2) must be between 0 and 1. y-values can exceed this range to create overshoot effects.
  136. ### Spring Animations
  137. Spring animations use a physics-based model for natural-feeling motion. Great for interactive elements.
  138. ```tsx
  139. <EaseView
  140. animate={{ translateX: isOpen ? 200 : 0 }}
  141. transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
  142. />
  143. ```
  144. | Parameter | Type | Default | Description |
  145. | ----------- | -------- | ------- | ------------------------------------------------------------- |
  146. | `damping` | `number` | `15` | Friction β€” higher values reduce oscillation |
  147. | `stiffness` | `number` | `120` | Spring constant β€” higher values mean faster animation |
  148. | `mass` | `number` | `1` | Mass of the object β€” higher values mean slower, more momentum |
  149. | `velocity` | `number` | `0` | Initial velocity in property units per second (native only) |
  150. | `delay` | `number` | `0` | Delay in milliseconds before the animation starts |
  151. `velocity` gives the spring a head start, the way `Animated.spring`'s `velocity` does β€” useful
  152. when the animation continues a gesture that was already moving. It is signed in value space, so a
  153. positive value means the property is already increasing:
  154. ```tsx
  155. <EaseView
  156. animate={{ translateY: dismissed ? 400 : 0 }}
  157. transition={{ type: 'spring', damping: 18, stiffness: 200, velocity: 1200 }}
  158. />
  159. ```
  160. Units follow the JS side β€” DIPs per second for `translateX`/`translateY`, degrees per second for
  161. `rotate`, and plain units per second for `scale` and `opacity`. It has no effect on web, where a
  162. spring compiles to a single normalized CSS easing curve that cannot express a per-property
  163. starting velocity.
  164. Spring presets for common feels:
  165. ```tsx
  166. // Snappy (no bounce)
  167. { type: 'spring', damping: 20, stiffness: 300, mass: 1 }
  168. // Gentle bounce
  169. { type: 'spring', damping: 12, stiffness: 120, mass: 1 }
  170. // Bouncy
  171. { type: 'spring', damping: 8, stiffness: 200, mass: 1 }
  172. // Slow and heavy
  173. { type: 'spring', damping: 20, stiffness: 60, mass: 2 }
  174. ```
  175. ### Disabling Animations
  176. Use `{ type: 'none' }` to apply values immediately without animation. Useful for skipping animations in reduced-motion modes or when you need an instant state change.
  177. ```tsx
  178. <EaseView
  179. animate={{ opacity: isVisible ? 1 : 0 }}
  180. transition={{ type: 'none' }}
  181. />
  182. ```
  183. `onTransitionEnd` fires immediately with `{ finished: true }`.
  184. ### Per-Property Transitions
  185. Pass a map instead of a single config to use different animation types per property category.
  186. ```tsx
  187. <EaseView
  188. animate={{ opacity: visible ? 1 : 0, translateY: visible ? 0 : 30 }}
  189. transition={{
  190. opacity: { type: 'timing', duration: 150, easing: 'easeOut' },
  191. transform: { type: 'spring', damping: 12, stiffness: 200 },
  192. }}
  193. />
  194. ```
  195. Available category keys:
  196. | Key | Properties |
  197. | ----------------- | ---------------------------------------------------------------- |
  198. | `default` | Fallback for categories not explicitly listed |
  199. | `transform` | translateX, translateY, scaleX, scaleY, rotate, rotateX, rotateY |
  200. | `opacity` | opacity |
  201. | `borderRadius` | borderRadius |
  202. | `backgroundColor` | backgroundColor |
  203. | `border` | borderWidth, borderColor |
  204. | `shadow` | shadowOpacity, shadowRadius, shadowColor, shadowOffset, elevation |
  205. Use `default` as a fallback for categories not explicitly listed:
  206. ```tsx
  207. <EaseView
  208. animate={{ opacity: 1, scale: 1.2, translateY: -20 }}
  209. transition={{
  210. default: { type: 'spring', damping: 15, stiffness: 120 },
  211. opacity: { type: 'timing', duration: 200, easing: 'easeOut' },
  212. }}
  213. />
  214. ```
  215. When no `default` key is provided, the library default (timing 300ms easeInOut) applies to all categories.
  216. > **Android note:** Android animates `backgroundColor` with `ValueAnimator` (timing only). If a per-property map specifies `type: 'spring'` for `backgroundColor`, it silently falls back to timing 300ms.
  217. ### Border Radius
  218. `borderRadius` can be animated just like other properties. It uses hardware-accelerated platform APIs β€” `ViewOutlineProvider` + `clipToOutline` on Android and `layer.cornerRadius` on iOS.
  219. ```tsx
  220. <EaseView
  221. animate={{ borderRadius: expanded ? 0 : 16 }}
  222. transition={{ type: 'timing', duration: 300 }}
  223. style={styles.card}
  224. >
  225. <Image source={heroImage} style={styles.image} />
  226. <Text>Content is clipped to rounded corners</Text>
  227. </EaseView>
  228. ```
  229. When `borderRadius` is in `animate`, any `borderRadius` in `style` is automatically stripped to avoid conflicts.
  230. ### Background Color
  231. `backgroundColor` can be animated using any React Native color value. Colors are converted to native ARGB integers via `processColor()`.
  232. ```tsx
  233. <EaseView
  234. animate={{ backgroundColor: isActive ? '#3B82F6' : '#E5E7EB' }}
  235. transition={{ type: 'timing', duration: 300 }}
  236. style={styles.card}
  237. >
  238. <Text>Tap to change color</Text>
  239. </EaseView>
  240. ```
  241. On Android, background color uses `ValueAnimator.ofArgb()` (timing only β€” spring is not supported for colors). On iOS, it uses `CAAnimation` on the `backgroundColor` layer key path and supports both timing and spring transitions.
  242. > **Note:** On Android, background color animation uses `ValueAnimator.ofArgb()` which only supports timing transitions. Spring transitions for `backgroundColor` are not supported on Android and will fall back to timing with the default duration. On iOS, both timing and spring transitions work for background color.
  243. When `backgroundColor` is in `animate`, any `backgroundColor` in `style` is automatically stripped to avoid conflicts.
  244. ### Border
  245. `borderWidth` and `borderColor` can be animated. On iOS, these use Core Animation on the `CALayer` border properties. On Android, they use `BackgroundStyleApplicator` which updates the `BorderDrawable` each frame.
  246. ```tsx
  247. <EaseView
  248. animate={{
  249. borderWidth: selected ? 3 : 0,
  250. borderColor: selected ? '#3B82F6' : '#E5E7EB',
  251. }}
  252. transition={{ border: { type: 'spring', damping: 15, stiffness: 120 } }}
  253. style={styles.card}
  254. />
  255. ```
  256. ### Shadow / Elevation
  257. Shadow properties are iOS-only (`shadowOpacity`, `shadowRadius`, `shadowColor`, `shadowOffset`). On Android, use `elevation` for material shadows.
  258. ```tsx
  259. <EaseView
  260. animate={{
  261. shadowOpacity: active ? 0.4 : 0,
  262. shadowRadius: active ? 16 : 0,
  263. shadowOffset: active ? { width: 0, height: 8 } : { width: 0, height: 0 },
  264. elevation: active ? 12 : 0,
  265. }}
  266. transition={{ shadow: { type: 'spring', damping: 15, stiffness: 120 } }}
  267. style={{ shadowColor: '#000', backgroundColor: '#fff', borderRadius: 16 }}
  268. />
  269. ```
  270. ### Animatable Properties
  271. All properties are set in the `animate` prop as flat values (no transform array).
  272. ```tsx
  273. <EaseView
  274. animate={{
  275. opacity: 1, // 0 to 1
  276. translateX: 0, // pixels
  277. translateY: 0, // pixels
  278. scale: 1, // 1 = normal size (shorthand for scaleX + scaleY)
  279. scaleX: 1, // horizontal scale
  280. scaleY: 1, // vertical scale
  281. rotate: 0, // Z-axis rotation in degrees
  282. rotateX: 0, // X-axis rotation in degrees (3D)
  283. rotateY: 0, // Y-axis rotation in degrees (3D)
  284. borderRadius: 0, // pixels (hardware-accelerated)
  285. backgroundColor: 'transparent', // any RN color value
  286. borderWidth: 0, // pixels
  287. borderColor: 'black', // any RN color value
  288. shadowOpacity: 0, // 0–1 (iOS only)
  289. shadowRadius: 0, // pixels (iOS only)
  290. shadowColor: 'black', // any RN color value (iOS only)
  291. shadowOffset: { width: 0, height: 0 }, // iOS only
  292. elevation: 0, // Android material shadow
  293. }}
  294. />
  295. ```
  296. `scale` is a shorthand that sets both `scaleX` and `scaleY`. When `scaleX` or `scaleY` is also specified, it overrides the `scale` value for that axis.
  297. You can animate any combination of properties simultaneously. Use a single transition config for all properties, or a [per-property map](#per-property-transitions) for different configs per category.
  298. ### Looping Animations
  299. Timing animations can loop infinitely. Use `'repeat'` to restart from the beginning or `'reverse'` to alternate direction.
  300. ```tsx
  301. // Pulsing opacity
  302. <EaseView
  303. initialAnimate={{ opacity: 0.3 }}
  304. animate={{ opacity: 1 }}
  305. transition={{ type: 'timing', duration: 1000, easing: 'easeInOut', loop: 'reverse' }}
  306. />
  307. // Marquee-style scroll
  308. <EaseView
  309. initialAnimate={{ translateX: 0 }}
  310. animate={{ translateX: -300 }}
  311. transition={{ type: 'timing', duration: 3000, easing: 'linear', loop: 'repeat' }}
  312. />
  313. ```
  314. Loop requires `initialAnimate` to define the starting value. Spring animations do not support looping.
  315. ### Pausing Animations
  316. Set `paused` to freeze a view's running animations, loops included, where they are. Setting it back to `false` resumes them from the same point. Nothing is remounted, so children (and their images) are untouched.
  317. ```tsx
  318. <EaseView
  319. initialAnimate={{ translateX: 0 }}
  320. animate={{ translateX: -300 }}
  321. transition={{ type: 'timing', duration: 3000, easing: 'linear', loop: 'repeat' }}
  322. paused={touching}
  323. onPaused={({ values }) => console.log(values.translateX)}
  324. />
  325. ```
  326. `onPaused` fires each time `paused` becomes `true`, with the values on screen at that moment for the keys set in `animate` (colors as `rgba()` strings).
  327. While paused:
  328. - Changing `animate` starts the new animations from the frozen values; they play once resumed. A `delay` counts from the resume.
  329. - `transition: { type: 'none' }` still applies its values immediately, as does removing a property from `animate`.
  330. - Toggling `paused` is a prop update, so like any re-render it reports in-flight non-looping animations to `onTransitionEnd` as interrupted, and their completion after the resume is not reported.
  331. Platform notes:
  332. - **iOS** stops the view layer's Core Animation clock, so Core Animation animations of descendant views pause too. After a resume that clock runs behind `CACurrentMediaTime()`, so a descendant animation that sets its `beginTime` from `CACurrentMediaTime()` instead of its layer's time starts late. `rotate` values come from the presentation transform, normalized to (-180, 180].
  333. - **Android** pauses timing animators in place. `ValueAnimator` records the pause one frame after the last value it drew, so a resume can land up to one frame ahead. `SpringAnimation` can't pause, so a spring stops and restarts from the same value and velocity on resume.
  334. - **Web** pauses the element's own CSS transitions and animations. Changing a loop's `animate` restarts it from `initialAnimate`, paused or not. With `rotateX`/`rotateY` (3D transforms), transform values in `onPaused` report their targets.
  335. ### Enter Animations
  336. Use `initialAnimate` to set starting values. On mount, the view starts at `initialAnimate` values and animates to `animate` values.
  337. ```tsx
  338. // Fade in and slide up on mount
  339. <EaseView
  340. initialAnimate={{ opacity: 0, translateY: 20 }}
  341. animate={{ opacity: 1, translateY: 0 }}
  342. transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
  343. />
  344. ```
  345. Without `initialAnimate`, the view renders at the `animate` values immediately with no animation on mount.
  346. ### Delay
  347. Use `delay` to postpone the start of an animation. This is useful for staggering enter animations across multiple elements.
  348. ```tsx
  349. // Staggered fade-in list
  350. {items.map((item, i) => (
  351. <EaseView
  352. key={item.id}
  353. initialAnimate={{ opacity: 0, translateY: 20 }}
  354. animate={{ opacity: 1, translateY: 0 }}
  355. transition={{ type: 'timing', duration: 300, delay: i * 100 }}
  356. >
  357. <Text>{item.label}</Text>
  358. </EaseView>
  359. ))}
  360. ```
  361. `delay` works with both timing and spring transitions.
  362. ### Interruption
  363. Animations are interruptible by default. If you change `animate` values while an animation is running, it smoothly redirects to the new target from wherever it currently is β€” no jumping or restarting.
  364. ```tsx
  365. // Rapidly toggling this is fine β€” each toggle smoothly
  366. // redirects the animation from its current position
  367. <EaseView
  368. animate={{ translateX: isLeft ? 0 : 200 }}
  369. transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
  370. />
  371. ```
  372. ### Transform Origin
  373. By default, scale and rotation animate from the view's center. Use `transformOrigin` to change the pivot point with 0–1 fractions.
  374. ```tsx
  375. // Rotate from top-left corner
  376. <EaseView
  377. animate={{ rotate: isOpen ? 45 : 0 }}
  378. transformOrigin={{ x: 0, y: 0 }}
  379. transition={{ type: 'spring', damping: 12, stiffness: 200, mass: 1 }}
  380. style={styles.card}
  381. />
  382. // Scale from bottom-right
  383. <EaseView
  384. animate={{ scale: active ? 1.2 : 1 }}
  385. transformOrigin={{ x: 1, y: 1 }}
  386. transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
  387. style={styles.card}
  388. />
  389. ```
  390. | Value | Position |
  391. | -------------------- | ---------------- |
  392. | `{ x: 0, y: 0 }` | Top-left |
  393. | `{ x: 0.5, y: 0.5 }` | Center (default) |
  394. | `{ x: 1, y: 1 }` | Bottom-right |
  395. ### Transform Perspective
  396. Control the 3D perspective depth for `rotateX` and `rotateY` animations. Lower values create a more dramatic 3D effect; higher values look flatter.
  397. ```tsx
  398. <EaseView
  399. animate={{ rotateY: flipped ? 180 : 0 }}
  400. transformPerspective={800}
  401. transition={{ type: 'timing', duration: 600, easing: 'easeInOut' }}
  402. style={styles.card}
  403. />
  404. ```
  405. Default is `1280`, matching React Native's default perspective.
  406. > **iOS note:** On iOS, the parent view must not be flattened by Fabric for perspective to render correctly. Ensure the parent has `collapsable={false}` or a style that prevents flattening (e.g. `transform`, `opacity`, `zIndex`).
  407. ### Style Handling
  408. `EaseView` accepts all standard `ViewStyle` properties. If a property appears in both `style` and `animate`, the animated value takes priority and the style value is stripped. A dev warning is logged when this happens.
  409. ```tsx
  410. // opacity in style works because only translateY is animated
  411. <EaseView
  412. animate={{ translateY: moved ? -10 : 0 }}
  413. transition={{ type: 'spring', damping: 15, stiffness: 120, mass: 1 }}
  414. style={{
  415. opacity: 0.9,
  416. backgroundColor: 'white',
  417. borderRadius: 16,
  418. padding: 16,
  419. }}
  420. >
  421. <Text>Notification card</Text>
  422. </EaseView>
  423. // ⚠️ opacity is in both β€” animate wins, style opacity is stripped, dev warning logged
  424. <EaseView
  425. animate={{ opacity: 1 }}
  426. style={{ opacity: 0.5, backgroundColor: 'white' }}
  427. />
  428. ```
  429. ## API Reference
  430. ### `<EaseView>`
  431. A `View` that animates property changes using native platform APIs.
  432. | Prop | Type | Description |
  433. | ------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
  434. | `animate` | `AnimateProps` | Target values for animated properties |
  435. | `initialAnimate` | `AnimateProps` | Starting values for enter animations (animates to `animate` on mount) |
  436. | `transition` | `Transition` | Animation configuration β€” a single config (timing, spring, or none) or a [per-property map](#per-property-transitions) |
  437. | `onTransitionEnd` | `(event) => void` | Called when all animations complete with `{ finished: boolean }` |
  438. | `paused` | `boolean` | Freezes running animations in place and resumes them from there when `false`. See [Pausing Animations](#pausing-animations). Default: `false` |
  439. | `onPaused` | `(event) => void` | Called when `paused` takes effect, with `{ values }`: the on-screen values of the keys set in `animate` |
  440. | `transformOrigin` | `{ x?: number; y?: number }` | Pivot point for scale/rotation as 0–1 fractions. Default: `{ x: 0.5, y: 0.5 }` (center) |
  441. | `transformPerspective` | `number` | Camera distance for 3D transforms (`rotateX`, `rotateY`). See [Transform Perspective](#transform-perspective). Default: `1280` |
  442. | `useHardwareLayer` | `boolean` | Android only β€” rasterize to GPU texture during animations. See [Hardware Layers](#hardware-layers-android). Default: `false` |
  443. | `className` | `string` | NativeWind / Uniwind / Tailwind CSS class string. Requires NativeWind or Uniwind in your project. |
  444. | `style` | `ViewStyle` | Non-animated styles (layout, colors, borders, etc.) |
  445. | `children` | `ReactNode` | Child elements |
  446. | ...rest | `ViewProps` | All other standard View props |
  447. ### `AnimateProps`
  448. | Property | Type | Default | Description |
  449. | ----------------- | ------------ | --------------- | ------------------------------------------------------------------------------------ |
  450. | `opacity` | `number` | `1` | View opacity (0–1) |
  451. | `translateX` | `number` | `0` | Horizontal translation in pixels |
  452. | `translateY` | `number` | `0` | Vertical translation in pixels |
  453. | `scale` | `number` | `1` | Uniform scale factor (shorthand for `scaleX` + `scaleY`) |
  454. | `scaleX` | `number` | `1` | Horizontal scale factor (overrides `scale` for X axis) |
  455. | `scaleY` | `number` | `1` | Vertical scale factor (overrides `scale` for Y axis) |
  456. | `rotate` | `number` | `0` | Z-axis rotation in degrees |
  457. | `rotateX` | `number` | `0` | X-axis rotation in degrees (3D) |
  458. | `rotateY` | `number` | `0` | Y-axis rotation in degrees (3D) |
  459. | `borderRadius` | `number` | `0` | Border radius in pixels (hardware-accelerated) |
  460. | `backgroundColor` | `ColorValue` | `'transparent'` | Background color (any RN color value). Timing-only on Android, spring+timing on iOS. |
  461. | `borderWidth` | `number` | `0` | Border width in pixels |
  462. | `borderColor` | `ColorValue` | `'black'` | Border color |
  463. | `shadowOpacity` | `number` | `0` | Shadow opacity 0–1 (iOS only) |
  464. | `shadowRadius` | `number` | `0` | Shadow blur radius (iOS only) |
  465. | `shadowColor` | `ColorValue` | `'black'` | Shadow color (iOS only) |
  466. | `shadowOffset` | `object` | `{width:0,height:0}` | Shadow offset `{ width, height }` (iOS only) |
  467. | `elevation` | `number` | `0` | Material shadow elevation (Android only) |
  468. Properties not specified in `animate` default to their identity values.
  469. ### `TimingTransition`
  470. ```tsx
  471. {
  472. type: 'timing';
  473. duration?: number; // default: 300 (ms)
  474. easing?: EasingType; // default: 'easeInOut' β€” preset name or [x1, y1, x2, y2]
  475. delay?: number; // default: 0 (ms)
  476. loop?: 'repeat' | 'reverse'; // default: none
  477. }
  478. ```
  479. ### `SpringTransition`
  480. ```tsx
  481. {
  482. type: 'spring';
  483. damping?: number; // default: 15
  484. stiffness?: number; // default: 120
  485. mass?: number; // default: 1
  486. velocity?: number; // default: 0 (property units/s, native only)
  487. delay?: number; // default: 0 (ms)
  488. }
  489. ```
  490. ### `NoneTransition`
  491. ```tsx
  492. {
  493. type: 'none';
  494. }
  495. ```
  496. Applies values instantly with no animation. `onTransitionEnd` fires immediately with `{ finished: true }`.
  497. ### `TransitionMap`
  498. A per-property map that applies different transition configs to different property categories. See [Per-Property Transitions](#per-property-transitions).
  499. | Key | Properties |
  500. | ----------------- | ---------------------------------------------------------------- |
  501. | `default` | Fallback for categories not explicitly listed |
  502. | `transform` | translateX, translateY, scaleX, scaleY, rotate, rotateX, rotateY |
  503. | `opacity` | opacity |
  504. | `borderRadius` | borderRadius |
  505. | `backgroundColor` | backgroundColor |
  506. | `border` | borderWidth, borderColor |
  507. | `shadow` | shadowOpacity, shadowRadius, shadowColor, shadowOffset, elevation |
  508. ## Hardware Layers (Android)
  509. Setting `useHardwareLayer` rasterizes the view into a GPU texture for the duration of the animation. This means animated property changes (opacity, scale, rotation) are composited on the RenderThread without redrawing the view hierarchy β€” useful for complex views with many children.
  510. ```tsx
  511. <EaseView animate={{ opacity: isVisible ? 1 : 0 }} useHardwareLayer />
  512. ```
  513. **Trade-offs:**
  514. - Faster rendering for opacity, scale, and rotation animations (RenderThread compositing).
  515. - Uses additional GPU memory for the off-screen texture (proportional to view size).
  516. - Children that overflow the view's layout bounds are **clipped** by the texture. This causes visual artifacts when animating `translateX`/`translateY` on views with overflowing content.
  517. No-op on iOS where Core Animation already composites off the main thread.
  518. ## Benchmarks
  519. The example app includes a benchmark that measures per-frame animation overhead across different approaches. All approaches run the same animation (translateX loop, linear, 2s) on a configurable number of views.
  520. ### Android (release build, emulator, M4 MacBook Pro)
  521. UI thread time per frame: anim + layout + draw (ms). Lower is better.
  522. ![Android benchmark](https://github.com/user-attachments/assets/f0e5cf26-76be-4dd3-ae04-e17c6d13b49c)
  523. <details>
  524. <summary>Detailed numbers</summary>
  525. | Views | Metric | Ease | Reanimated SV | Reanimated SV (FF) | Reanimated CSS | Reanimated CSS (FF) | RN Animated |
  526. |-------|--------|------|---------------|---------------------|----------------|----------------------|-------------|
  527. | 10 | Avg | 0.21 | 1.15 | 0.75 | 0.99 | 0.45 | 0.36 |
  528. | 10 | P95 | 0.33 | 1.70 | 1.53 | 1.44 | 0.80 | 0.62 |
  529. | 10 | P99 | 0.48 | 1.94 | 2.26 | 1.62 | 1.35 | 0.98 |
  530. | 100 | Avg | 0.36 | 2.71 | 1.81 | 2.19 | 1.01 | 0.71 |
  531. | 100 | P95 | 0.56 | 3.09 | 2.29 | 2.67 | 1.91 | 1.08 |
  532. | 100 | P99 | 0.71 | 3.20 | 2.63 | 2.97 | 2.25 | 1.36 |
  533. | 500 | Avg | 0.60 | 8.31 | 5.37 | 5.50 | 2.37 | 1.60 |
  534. | 500 | P95 | 0.75 | 9.26 | 6.36 | 6.34 | 2.86 | 1.88 |
  535. | 500 | P99 | 0.87 | 9.59 | 6.89 | 6.88 | 3.22 | 3.84 |
  536. </details>
  537. ### iOS (release build, simulator, iPhone 16 Pro, M4 MacBook Pro)
  538. Display link callback time per frame (ms). Lower is better.
  539. ![iOS benchmark](https://github.com/user-attachments/assets/c39a7a71-bf21-4276-b02f-b29983989832)
  540. <details>
  541. <summary>Detailed numbers</summary>
  542. | Views | Metric | Ease | Reanimated SV | Reanimated SV (FF) | Reanimated CSS | Reanimated CSS (FF) | RN Animated |
  543. |-------|--------|------|---------------|---------------------|----------------|----------------------|-------------|
  544. | 10 | Avg | 0.01 | 1.33 | 1.08 | 1.06 | 0.63 | 0.83 |
  545. | 10 | P95 | 0.02 | 1.67 | 1.59 | 1.34 | 1.01 | 1.18 |
  546. | 10 | P99 | 0.03 | 1.90 | 1.68 | 1.50 | 1.08 | 1.31 |
  547. | 100 | Avg | 0.01 | 3.72 | 3.33 | 2.71 | 2.48 | 3.32 |
  548. | 100 | P95 | 0.01 | 5.21 | 4.50 | 3.83 | 3.39 | 4.28 |
  549. | 100 | P99 | 0.02 | 5.68 | 4.75 | 4.91 | 3.79 | 4.55 |
  550. | 500 | Avg | 0.01 | 6.84 | 6.54 | 4.16 | 3.70 | 4.91 |
  551. | 500 | P95 | 0.01 | 7.69 | 7.32 | 4.59 | 4.22 | 5.66 |
  552. | 500 | P99 | 0.02 | 8.10 | 7.45 | 4.71 | 4.33 | 5.89 |
  553. </details>
  554. Ease stays near zero because animations run entirely on platform APIs. On iOS, Core Animation runs on a separate render server process off the main thread, which is why Ease shows ~0ms. On Android, ObjectAnimator runs on the UI thread but is significantly lighter than other approaches. Reanimated results shown with experimental [feature flags](https://docs.swmansion.com/react-native-reanimated/docs/guides/feature-flags/) OFF (default) and ON (FF). Run the benchmark yourself in the [example app](example/).
  555. ## How It Works
  556. `EaseView` is a native Fabric component. The JS side flattens your `animate` and `transition` props into flat native props. When those props change, the native view:
  557. 1. **Diffs** previous vs new values to find what changed
  558. 2. **Reads** the current in-flight value (for smooth interruption)
  559. 3. **Creates** a platform-native animation from the current value to the new target
  560. 4. **Sets** the final value immediately on the model layer
  561. On iOS, this uses `CABasicAnimation`/`CASpringAnimation` on `CALayer` key paths. On Android, this uses `ObjectAnimator`/`SpringAnimation` on `View` properties. No JS thread involvement during the animation.
  562. ## Requirements
  563. - React Native 0.76+ (new architecture / Fabric)
  564. - iOS 15.1+
  565. - Android minSdk 24+
  566. ## Contributing
  567. - [Development workflow](CONTRIBUTING.md#development-workflow)
  568. - [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
  569. - [Code of conduct](CODE_OF_CONDUCT.md)
  570. ## License
  571. MIT
  572. ---
  573. Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.