Custom animations
Use a custom animation when the SharedTransition modifiers are not sufficient, for example for a curved path or a different timing for each property. You write a worklet that gets the values of the two views and returns an animation for each style property.
Reference
import Animated, {
SharedTransition,
withSpring,
withTiming,
} from 'react-native-reanimated';
const transition = SharedTransition.custom((values) => {
'worklet';
return {
originX: withTiming(values.targetOriginX, { duration: 600 }),
originY: withSpring(values.targetOriginY),
width: withTiming(values.targetWidth, { duration: 600 }),
height: withTiming(values.targetHeight, { duration: 600 }),
};
});
function Photo() {
return (
<Animated.View
sharedTransitionTag="photo"
sharedTransitionStyle={transition}
/>
);
}


Type definitions
type CustomSharedTransitionAnimation = (
values: SharedTransitionAnimationsValues
) => StyleProps;
class SharedTransition {
static custom(animation: CustomSharedTransitionAnimation): SharedTransition;
custom(animation: CustomSharedTransitionAnimation): this;
// ...
}
Arguments
animation
A worklet that gets values and returns an object with an animation, for example from withTiming or withSpring, for each style property that you want to animate.
The worklet returns the animations directly. This is different from custom layout animations, which return { initialValues, animations }. Every animation starts from the value of the source view.
values has the values of the source view with the current prefix, the values of the target view with the target prefix, and the size of the window:
| Value | Description |
|---|---|
currentOriginX, targetOriginX | The x coordinate of the top-left corner, in window coordinates. |
currentOriginY, targetOriginY | The y coordinate of the top-left corner, in window coordinates. |
currentWidth, targetWidth | The width of the view. |
currentHeight, targetHeight | The height of the view. |
currentOpacity, targetOpacity | The opacity of the view, multiplied by the opacities of its ancestors. |
currentBackgroundColor, targetBackgroundColor | The background color. |
currentBorderRadius, targetBorderRadius | The border radius. Per-corner values, for example currentBorderTopLeftRadius, show when one of the views sets them. |
currentBorderWidth, targetBorderWidth | The border width. Per-side values, for example currentBorderLeftWidth, show when one of the views sets them. |
currentBorderColor, targetBorderColor | The border color. Per-side values, for example currentBorderLeftColor, show when one of the views sets them. |
currentTransform, targetTransform | The transform as { matrix }, a flat 4×4 matrix. |
currentTransformOrigin, targetTransformOrigin | The transform origin as [x, y, z]. |
currentBoxShadow, targetBoxShadow | The box shadows. |
currentShadowColor, currentShadowOffset, currentShadowOpacity, currentShadowRadius and the target values | The shadow* properties. |
currentElevation, targetElevation | The elevation, on Android only. |
currentClipOriginX, currentClipOriginY, currentClipWidth, currentClipHeight, currentClipBorderRadius and the target values | The clip of the moving view in window coordinates: the bounds of the ancestors that clip their content, with overflow: 'hidden' or 'scroll'. At an end without such an ancestor, the clip is the frame of the view, or the window when the view can draw outside its frame. They are present only when an ancestor clips either view. |
windowWidth, windowHeight | The size of the window. |
Example
To move the view on a curve, give the two axes different curves:
const arc = SharedTransition.custom((values) => {
'worklet';
const config = { duration: 600 };
return {
originX: withTiming(values.targetOriginX, { ...config, easing: Easing.out(Easing.quad) }),
originY: withTiming(values.targetOriginY, { ...config, easing: Easing.in(Easing.quad) }),
width: withTiming(values.targetWidth, config),
height: withTiming(values.targetHeight, config),
borderRadius: withTiming(values.targetBorderRadius, config),
};
});
To animate the transform, animate the whole matrix:
const transition = SharedTransition.custom((values) => {
'worklet';
return {
transform: [{ matrix: withTiming(values.targetTransform.matrix) }],
};
});
Remarks
- The callback passed to
SharedTransition.customis automatically workletized and runs on the UI thread. - Reanimated does not animate the properties that you do not return. Such a property keeps the value of the source view until the transition ends.
- The clip is an exception: when you do not return the
clip*properties, they animate with the duration and the easing of the builder, in a straight line. If the view moves on a curve or with other timing, it can move outside of its clip. Return theclip*properties with the same animations asoriginX,originY,widthandheightto keep the view inside its clip. - The clip uses the bounds of the clipping ancestors without their transforms, also in the default transition. If such an ancestor is transformed, the clip does not follow it on screen. For example, a rounded card scaled by a press animation gives the view corners that do not match the card, and a sheet moved with
translateYmoves away from its clip. Scale or move the shared view itself instead. - Animate the transform as a whole, with
transform: [{ matrix }]. Separate transform operations, for exampletransform: [{ scale: withTiming(2) }], are not supported. - The worklet controls the timing of each animation. The
.delay()and.withCallback()modifiers of the builder still apply, for exampleSharedTransition.custom(animation).delay(100).
Platform compatibility
| Android | iOS | Web |
|---|---|---|
| ✅ | ✅ | ❌ |