Skip to main content
Version: Unreleased

Custom animations

Available from 4.8.0

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.

Loading...

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:

ValueDescription
currentOriginX, targetOriginXThe x coordinate of the top-left corner, in window coordinates.
currentOriginY, targetOriginYThe y coordinate of the top-left corner, in window coordinates.
currentWidth, targetWidthThe width of the view.
currentHeight, targetHeightThe height of the view.
currentOpacity, targetOpacityThe opacity of the view, multiplied by the opacities of its ancestors.
currentBackgroundColor, targetBackgroundColorThe background color.
currentBorderRadius, targetBorderRadiusThe border radius. Per-corner values, for example currentBorderTopLeftRadius, show when one of the views sets them.
currentBorderWidth, targetBorderWidthThe border width. Per-side values, for example currentBorderLeftWidth, show when one of the views sets them.
currentBorderColor, targetBorderColorThe border color. Per-side values, for example currentBorderLeftColor, show when one of the views sets them.
currentTransform, targetTransformThe transform as { matrix }, a flat 4×4 matrix.
currentTransformOrigin, targetTransformOriginThe transform origin as [x, y, z].
currentBoxShadow, targetBoxShadowThe box shadows.
currentShadowColor, currentShadowOffset, currentShadowOpacity, currentShadowRadius and the target valuesThe shadow* properties.
currentElevation, targetElevationThe elevation, on Android only.
currentClipOriginX, currentClipOriginY, currentClipWidth, currentClipHeight, currentClipBorderRadius and the target valuesThe 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, windowHeightThe 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.custom is 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 the clip* properties with the same animations as originX, originY, width and height to 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 translateY moves 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 example transform: [{ 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 example SharedTransition.custom(animation).delay(100).

Platform compatibility​

AndroidiOSWeb
✅✅❌