Changelogs

New in 3.4

Move older setups onto the 3.4-era layered transition surface.

The 3.4 Direction

If you are cleaning up an older setup, these are the migrations that matter:

  1. prefer Transition.Boundary.* for new bounds flows
  2. return layered interpolator output with content, backdrop, and surface
  3. prefer scoped interpolator state like current.layouts and current.snapIndex
  4. rename maskEnabled to navigationMaskEnabled
  5. rename expandViaScrollView to sheetScrollGestureBehavior
  6. move new embedded flows to blank stack instead of component stack

If you are already on v3.4 or v3.5 and want the current release changes, read Updating to 3.6 after this page.

Move New Bounds Flows To Transition.Boundary.*

Use explicit boundary ownership:

TSX

1<Transition.Boundary.Trigger id="hero" onPress={openDetail}>
2  <Card />
3</Transition.Boundary.Trigger>
4
5<Transition.Boundary.View id="hero">
6  <CardDetail />
7</Transition.Boundary.View>

Add Transition.Boundary.Target when the measured element is nested inside the owner:

TSX

1<Transition.Boundary.Trigger id="hero" onPress={openDetail}>
2  <View>
3    <Transition.Boundary.Target>
4      <Image source={image} />
5    </Transition.Boundary.Target>
6  </View>
7</Transition.Boundary.Trigger>

Return Layered Interpolator Output

3.4 treats the screen container as a layer system. Return slot objects instead of the old flat style keys:

TSX

1screenStyleInterpolator: () => ({
2  content: {
3    style: { opacity: 1 },
4  },
5  backdrop: {
6    style: { opacity: 0.4 },
7  },
8  surface: {
9    style: { borderRadius: 24 },
10  },
11});

The older flat keys are legacy compatibility input. New typed code should use layer slots instead:

  • contentStyle
  • backdropStyle
  • overlayStyle

If you used older background or backgroundComponent naming from earlier docs, move to surface and surfaceComponent.

Prefer Scoped Interpolator State

In 3.4, the interpolator gives you the full screen states directly:

  • previous
  • current
  • next
  • active
  • inactive

Prefer reading screen-specific data from those objects:

TSX

1screenStyleInterpolator: ({ current }) => {
2  "worklet";
3
4  const contentHeight = current.layouts.content?.height ?? 0;
5
6  return {
7    content: {
8      style: {
9        opacity: interpolate(current.snapIndex, [0, 1], [0.8, 1]),
10        transform: [{ translateY: contentHeight * (1 - current.progress) }],
11      },
12    },
13  };
14};

New code should prefer:

  • current.layouts
  • current.snapIndex

In current v3.6 code, use current.animatedSnapIndex when the visual state should follow a live gesture between detents. Use current.snapIndex for the selected target detent.

Rename Old Option Names

Use the 3.4 names:

TSX

1options={{
2  navigationMaskEnabled: true,
3  sheetScrollGestureBehavior: "expand-and-collapse",
4}}

Instead of:

TSX

1options={{
2  maskEnabled: true,
3  expandViaScrollView: true,
4}}

3.4 also adds the current snap-sheet surface:

  • snapPoints: ["auto", 1]
  • gestureReleaseVelocityScale
  • gestureSnapLocked

Prefer Blank Stack For Embedded Flows

createComponentStackNavigator() is now the legacy path.

If you previously used component stack for embedded or independent flows, move that work to blank stack:

TSX

1import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";
2
3const Stack = createBlankStackNavigator();
4
5<Stack.Navigator independent enableNativeScreens={false}>
6  {/* embedded flow */}
7</Stack.Navigator>

Blank stack now covers that use case directly and is the preferred path going forward.

For the v3 blank-stack model, including when to use independent and enableNativeScreens={false}, see Independent Stacks.

Hooks Now Target Ancestors Only

useScreenAnimation() and useScreenGesture() accept a target only:

TSX

1const selfAnimation = useScreenAnimation();
2const parentAnimation = useScreenAnimation({ depth: -1 });
3
4const selfGesture = useScreenGesture();
5const parentGesture = useScreenGesture({ depth: -1 });

useScreenGesture() returns a gesture ref for coordination with Gesture Handler. It does not configure gestureEnabled, gestureDirection, or other screen options.

Migration Checklist

  • move new bounds work to Transition.Boundary.Trigger, Transition.Boundary.View, and Transition.Boundary.Target
  • replace flat interpolator keys with content, backdrop, and surface
  • move layouts and snapIndex reads to current.layouts and current.snapIndex
  • rename maskEnabled to navigationMaskEnabled
  • rename expandViaScrollView to sheetScrollGestureBehavior
  • move new embedded flows from component stack to blank stack