@rootnative/inertia-gradients
v0.0.29
Published
Animated linear gradient primitive for @rootnative/inertia, built on expo-linear-gradient.
Maintainers
Readme
@rootnative/inertia-gradients
Animatable linear gradient primitive for @rootnative/inertia, built on expo-linear-gradient.
MotionLinearGradient accepts the same initial, animate, and transition shape as the core Motion.* primitives, with the animatable keys colors, start, end, and locations.
Install
pnpm add @rootnative/inertia-gradients expo-linear-gradientexpo-linear-gradient works in a bare React Native project and in Expo, but it's an Expo Module. A bare project needs the Expo modules runtime. See Installing Expo modules.
Peer dependencies: @rootnative/inertia (workspace or installed), react >=19.3.0, react-native >=0.88.0 <0.89.0, react-native-reanimated >=4.7.0 <4.8.0, expo >=58.0.0 <59.0.0, expo-linear-gradient >=58.0.0 <59.0.0.
Usage
import { StyleSheet } from 'react-native'
import { MotionLinearGradient } from '@rootnative/inertia-gradients'
export function Hero() {
return (
<MotionLinearGradient
colors={['#0f172a', '#1e293b']}
animate={{ colors: ['#7c3aed', '#0ea5e9'] }}
transition={{ type: 'timing', duration: 600 }}
style={StyleSheet.absoluteFill}
/>
)
}The static colors prop sets the visual on the first render and locks the slot count for the lifetime of the component. To resize the gradient (for example, from 2 stops to 3 stops), remount it with key={...}. The component throws in dev if colors.length changes between renders.
Animatable props
| Key | Shape | Notes |
| ----------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| colors | readonly string[] | Element-wise color interpolation via Reanimated's color setter. Length must match the static colors prop. |
| start | { x: number, y: number } | Normalized [0, 1] coordinates. x and y animate independently. |
| end | { x: number, y: number } | Same shape as start. |
| locations | readonly number[] | Optional stop positions. If supplied at mount, must remain supplied and same-length as colors for the component's lifetime. |
Per-property transitions work the same as in the core primitives:
<MotionLinearGradient
colors={['#000', '#000']}
animate={{
colors: ['#7c3aed', '#0ea5e9'],
start: { x: 0, y: 0 },
end: { x: 1, y: 1 },
}}
transition={{
colors: { type: 'timing', duration: 600 },
start: { type: 'spring', tension: 80, friction: 14 },
end: { type: 'spring', tension: 80, friction: 14 },
}}
/>initial
Pass initial to override the values of the mount frame, so the component starts somewhere other than the static props. Pass initial={false} to start at the animate target with no mount animation.
<MotionLinearGradient
colors={['#111', '#222']}
initial={{ colors: ['#000', '#000'] }} // fade up from black
animate={{ colors: ['#7c3aed', '#0ea5e9'] }}
/>Reduced motion
MotionLinearGradient follows <MotionConfig reducedMotion> the same as the core primitives. When the reduce-motion setting of the OS is on, a transition resolves as a direct assignment instead of withSpring or withTiming.
What this primitive doesn't do
- Radial or conic gradients. The primitive is linear only. Radial and conic are in the backlog, not scheduled.
- A slot-count resize. The length of the colors array is locked at mount.
- Sequence keyframes per stop.
animate.colorsaccepts one target array, not nested arrays. For chained gradient transitions, drive the target through state.
Documentation
- Full docs: https://rootnative.github.io/inertia/docs/gradients
- Core library:
@rootnative/inertia
AI agents: this package ships its own copy of the reference. Read node_modules/@rootnative/inertia-gradients/llms.txt for the full API. You need no network.
License
MIT © Root Native
