React Native Screen Transitions

https://screen-transitions.esjr.org
Admin
React Native Screen Transitions is a React Navigation transition toolkit for building custom screen...
Tokens:37,309
Snippets:470
Trust Score:4.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Verify setup with a basic navigator

Source: https://screen-transitions.esjr.org/installation

Test the installation by creating a stack navigator with a transition preset.

```tsx
1import Transition from "react-native-screen-transitions";
2import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";
3
4const Stack = createBlankStackNavigator();
5
6export function RootNavigator() {
7  return (
8    <Stack.Navigator>
9      <Stack.Screen name="Home" component={HomeScreen} />
10      <Stack.Screen
11        name="Detail"
12        component={DetailScreen}
13        options={{
14          ...Transition.Presets.SlideFromBottom(),
15        }}
16      />
17    </Stack.Navigator>
18  );
19}
```

--------------------------------

### Install the core package

Source: https://screen-transitions.esjr.org/installation

Install the primary library using npm.

```bash
npm install react-native-screen-transitions
```

--------------------------------

### Install peer dependencies

Source: https://screen-transitions.esjr.org/installation

Install required peer dependencies for React Navigation and Reanimated. Use expo install if working within an Expo project.

```bash
npm install react-native-reanimated react-native-gesture-handler @react-navigation/native @react-navigation/native-stack @react-navigation/elements react-native-screens react-native-safe-area-context
```

```bash
npx expo install react-native-reanimated react-native-gesture-handler \
  @react-navigation/native @react-navigation/native-stack \
  @react-navigation/elements react-native-screens \
  react-native-safe-area-context
```

--------------------------------

### Install iOS pods

Source: https://screen-transitions.esjr.org/installation

Run pod install in the iOS directory for bare React Native projects after adding new dependencies.

```bash
cd ios && pod install
```

--------------------------------

### Install optional masking dependency

Source: https://screen-transitions.esjr.org/installation

Install the masked view package if using navigation masks or legacy transition components.

```bash
npm install @react-native-masked-view/masked-view
```

--------------------------------

### Configure navigation.zoom()

Source: https://screen-transitions.esjr.org/navigation-zoom

Example configuration object for the navigation.zoom() function, demonstrating how to set custom border radius, target, backdrop properties, and drag response parameters.

```typescript
1return bounds(id).navigation.zoom({
2  borderRadius: 48,
3  target: "bound",
4  backgroundScale: 0.96,
5  backdropColor: "#000",
6  backdropOpacity: 0.45,
7  drag: {
8    translation: { horizontal: 0.9, vertical: 0.85 },
9    scale: { horizontal: 1, vertical: 0.8 },
10  },
11});
```

--------------------------------

### Install Peer Dependency

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Install the required react-native-teleport dependency when using handoff or escapeClipping features.

```bash
bun add react-native-teleport@1.1.10
```

--------------------------------

### Configure Nested Navigators with Different Directions

Source: https://screen-transitions.esjr.org/gesture-ownership

Demonstrates a setup where the parent navigator handles vertical gestures and the child screen handles horizontal gestures.

```TSX
import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";

const RootStack = createBlankStackNavigator();
const DetailsStack = createBlankStackNavigator();

function DetailsNavigator() {
  return (
    <DetailsStack.Navigator>
      <DetailsStack.Screen name="List" component={ListScreen} />
      <DetailsStack.Screen
        name="Card"
        component={CardScreen}
        options={{
          gestureEnabled: true,
          gestureDirection: "horizontal",
        }}
      />
    </DetailsStack.Navigator>
  );
}

function AppNavigator() {
  return (
    <RootStack.Navigator>
      <RootStack.Screen name="Home" component={HomeScreen} />
      <RootStack.Screen
        name="Details"
        component={DetailsNavigator}
        options={{
          gestureEnabled: true,
          gestureDirection: "vertical",
        }}
      />
    </RootStack.Navigator>
  );
}
```

--------------------------------

### Enable Initial Mount Animation

Source: https://screen-transitions.esjr.org/caveats

Use the experimental_animateOnInitialMount option to force the first screen in a stack to animate on initial mount.

```tsx
<Stack.Screen
  name="Home"
  component={HomeScreen}
  options={{
    experimental_animateOnInitialMount: true,
  }}
/>
```

--------------------------------

### Importing Transition components

Source: https://screen-transitions.esjr.org/transition-components

Basic imports for the main package and the blank stack navigator creator.

```tsx
import Transition, {
  withScreenTransitions,
  snapTo,
  type ScreenStyleInterpolator,
  type ScreenTransitionConfig,
} from "react-native-screen-transitions";

import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";
```

--------------------------------

### Targeting Screen Depths with Hooks

Source: https://screen-transitions.esjr.org/gestures

Demonstrates how to initialize gesture and animation refs for the current screen, parents, and grandparents using depth parameters.

```TSX
const selfGestureRef = useScreenGesture();
const parentGestureRef = useScreenGesture({ depth: -1 });
const grandparentGestureRef = useScreenGesture({ depth: -2 });

const parentAnimation = useScreenAnimation({ depth: -1 });
const childAnimation = useScreenAnimation({ depth: 1 });
```

--------------------------------

### Stack.Screen Backdrop Configuration

Source: https://screen-transitions.esjr.org/gestures

Configures how the backdrop behaves and renders during a screen transition using the options prop.

```APIDOC
## Stack.Screen Backdrop Configuration

### Description
Configures the backdrop behavior and custom component for a screen transition. Supported behaviors include "block", "passthrough", "dismiss", and "collapse".

### Parameters
- **backdropBehavior** (string) - Optional - Defines the interaction when tapping the backdrop.
- **backdropComponent** (ComponentType) - Optional - A custom component to render as the backdrop.
- **screenStyleInterpolator** (function) - Optional - A worklet function to interpolate backdrop styles based on transition progress.
```

--------------------------------

### Create a Blank Stack Navigator

Source: https://screen-transitions.esjr.org/quick-start

Initializes a stack navigator using createBlankStackNavigator and applies a built-in transition preset to a screen.

```typescript
1import Transition from "react-native-screen-transitions";
2import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";
3
4const Stack = createBlankStackNavigator();
5
6export function RootNavigator() {
7return (
8  <Stack.Navigator>
9    <Stack.Screen name="Home" component={HomeScreen} />
10    <Stack.Screen
11      name="Detail"
12      component={DetailScreen}
13      options={{
14        ...Transition.Presets.SlideFromBottom(),
15      }}
16    />
17  </Stack.Navigator>
18);
19}
```

--------------------------------

### inactiveBehavior Configuration

Source: https://screen-transitions.esjr.org/inactive-behavior

Example of configuring the inactiveBehavior option within a Stack.Screen component.

```APIDOC
## Configuration

### Description
Configures the lifecycle behavior of an inactive screen within a blank stack navigator.

### Usage
```tsx
const Stack = createBlankStackNavigator();

<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    inactiveBehavior: "hide",
  }}
/>
```

### Options
- **inactiveBehavior** (string) - Defines the behavior of the screen when it is no longer active. Defaults: "hide" (native), "unmount" (web).
```

--------------------------------

### Independent embedded flow

Source: https://screen-transitions.esjr.org/independent-stacks

Basic setup for an embedded flow that manages its own navigation state.

```TSX
<Stack.Navigator independent>
  <Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
```

--------------------------------

### Set Initial Snap Index

Source: https://screen-transitions.esjr.org/snap-points

Specifies the starting detent for the sheet using the initialSnapIndex property.

```tsx
<Stack.Screen
  name="sheet"
  component={SheetScreen}
  options={{
    gestureEnabled: true,
    gestureDirection: "vertical",
    snapPoints: [0.25, 0.5, 0.75, 1],
    initialSnapIndex: 1,
  }}
/>
```

--------------------------------

### Implement Zoom and Reveal transitions

Source: https://screen-transitions.esjr.org/shared-elements

Navigation helpers provide pre-built transition effects for zoom and masked reveal animations.

```tsx
screenStyleInterpolator: ({ bounds }) => {
  "worklet";

  return bounds("hero").navigation.zoom();
};
```

```tsx
screenStyleInterpolator: ({ bounds, active }) => {
  "worklet";

  const id = active.route.params?.revealId;
  if (!id) return null;

  return bounds(id).navigation.reveal({
    borderRadius: 48,
  });
};
```

--------------------------------

### blockTransition(routeKey?: string)

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Prevents a transition from starting for a specific route. This is used to coordinate the transition with asynchronous work on the destination screen.

```APIDOC
## blockTransition(routeKey)

### Description
Blocks the transition for the specified route. Calls are reference-counted; every call must be paired with an unblockTransition call.

### Parameters
- **routeKey** (string) - Optional - The key of the route to block. If omitted, uses the most recently focused screen.
```

--------------------------------

### Implementing Transition.Boundary with handoff

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-11

Configure a Boundary with the handoff prop to enable payload transfer between screens.

```TSX
<Transition.Boundary id="video" handoff>
  <Transition.Boundary.Target style={styles.video} />
</Transition.Boundary>
```

--------------------------------

### Configure Screen Transition Presets

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-7

Enable transitions and apply presets on a per-screen basis within the stack.

```tsx
<Stack.Screen
  name="Profile"
  component={ProfileScreen}
  options={{
    enableTransitions: true,
    ...Transition.Presets.SlideFromBottom(),
  }}
/>
```

--------------------------------

### Transition.Boundary.Host

Source: https://screen-transitions.esjr.org/transition-components

Defines an explicit coordinate space for handoff or clipping-escape content.

```APIDOC
## Transition.Boundary.Host

### Description
Used to place handoff or clipping-escape content within a specific local coordinate space, typically inside scrollable containers.
```

--------------------------------

### Apply transition specification

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Pair the zoom helper with a transition specification to ensure consistent timing during opening and closing.

```TSX
options={{
  transitionSpec: Transition.Specs.Zoom,
  screenStyleInterpolator: ({ bounds }) => {
    "worklet";
    return bounds(id).navigation.zoom();
  },
}}
```

--------------------------------

### Implement Live Payload Handoff

Source: https://screen-transitions.esjr.org/shared-elements

Use the handoff prop on matching Transition.Boundary components to move live payloads between screens without remounting.

```tsx
1// Source
2<Transition.Boundary id="video" handoff onPress={openPlayer}>
3  <Transition.Boundary.Target style={styles.video}>
4    <VideoView player={player} style={StyleSheet.absoluteFill} />
5  </Transition.Boundary.Target>
6</Transition.Boundary>
7
8// Destination
9<Transition.Boundary id="video" handoff>
10  <Transition.Boundary.Target style={styles.heroVideo} />
11</Transition.Boundary>
```

--------------------------------

### Update Gesture Options via useNavigation

Source: https://screen-transitions.esjr.org/gestures

Use setOptions to modify gesture behavior dynamically while the screen remains mounted.

```TSX
const navigation = useNavigation();

navigation.setOptions({
  gestureEnabled: false,
  gestureDirection: "pinch-in",
});
```

--------------------------------

### Configure Screen Transitions

Source: https://screen-transitions.esjr.org/adapters

Set enableTransitions to true and define transition specs and interpolators within the screen options.

```tsx
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    enableTransitions: true,
    gestureEnabled: true,
    transitionSpec: {
      open: Transition.Specs.DefaultSpec,
      close: Transition.Specs.DefaultSpec,
    },
    screenStyleInterpolator: () => {
      "worklet";

      return {
        content: {
          style: {
            // ...
          },
        },
      };
    },
  }}
/>;
```

--------------------------------

### Integrate Native Stack with Transitions

Source: https://screen-transitions.esjr.org/stack-types

Use the native-stack adapter to opt specific screens into custom transitions while maintaining native-stack behavior.

```TSX
const NativeStack = createNativeStackNavigator();
const Stack = withScreenTransitions(NativeStack);

<Stack.Navigator>
  <Stack.Screen
    name="Detail"
    component={DetailScreen}
    options={{
      enableTransitions: true,
      ...Transition.Presets.SlideFromBottom(),
    }}
  />
</Stack.Navigator>
```

--------------------------------

### Configure Blank Stack for Embedded Flows

Source: https://screen-transitions.esjr.org/changelog/migrating-to-3-4

Use createBlankStackNavigator for embedded or independent flows instead of the legacy component 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>
```

--------------------------------

### Implement a Blank Stack Navigator

Source: https://screen-transitions.esjr.org/stack-types

Use the blank stack navigator for full control over custom motion, gestures, and transitions without native-stack constraints.

```TSX
const Stack = createBlankStackNavigator();

<Stack.Navigator>
  <Stack.Screen name="Home" component={HomeScreen} />
  <Stack.Screen
    name="Detail"
    component={DetailScreen}
    options={{
      ...Transition.Presets.SlideFromBottom(),
      gestureEnabled: true,
    }}
  />
</Stack.Navigator>
```

--------------------------------

### navigation.reveal()

Source: https://screen-transitions.esjr.org/reveal

Configures the reveal transition behavior and mask properties.

```APIDOC
## navigation.reveal()

### Description
Pass options directly to navigation.reveal() to tune the transition defaults.

### Parameters
- **borderRadius** (number) - Optional - Destination mask border radius. Reveal interpolates from the measured source radius to this value.
- **borderContinuous** (boolean) - Optional - Uses React Native's continuous border curve for the reveal mask. Default: true.
- **maxSensitivity** (number) - Optional - Highest gesture sensitivity reveal applies before it reduces sensitivity during deeper drags. Default: 0.8.
- **velocityDepth** (number) - Optional - Velocity-driven depth for the dismiss scale orbit. Set 0 to remove the velocity depth effect. Default: 0.5.
- **backgroundScale** (number) - Optional - Scales the unfocused background content while the reveal runs above it. Default: 0.9375.
- **shouldBackgroundScaleResetOnSettled** (boolean) - Optional - Restores the unfocused background content to scale 1 once the reveal is visually settled. Default: true.
- **disablePointerEventsTillElementTransition** (boolean) - Optional - Blocks pointer-event pass-through on the inactive content until the source element handoff reaches progress 0.25. Default: true.
- **maskSizingMode** (MaskSizingMode) - Optional - Controls how the navigation mask element resizes. Valid values: "auto", "transform", "size". Default: "auto".
```

--------------------------------

### Using Transition Progress

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-8

Utilize transitionProgress to drive animations based on committed transition or snap progress, excluding live gesture movement.

```TSX
screenStyleInterpolator: ({ current }) => {
  "worklet";

  return {
    content: {
      style: {
        opacity: current.transitionProgress,
      },
    },
  };
};
```

--------------------------------

### Wrap Native Stack with withScreenTransitions

Source: https://screen-transitions.esjr.org/adapters

Use withScreenTransitions to make a native-stack navigator transition-aware.

```tsx
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import Transition, {
  withScreenTransitions,
} from "react-native-screen-transitions";

const NativeStack = createNativeStackNavigator();
const Stack = withScreenTransitions(NativeStack);
```

--------------------------------

### Static factory configuration

Source: https://screen-transitions.esjr.org/independent-stacks

Configure independent and native screen settings using the static factory API.

```TSX
import { createBlankStackNavigator } from "react-native-screen-transitions/react-navigation";

const Stack = createBlankStackNavigator({
  independent: true,
  enableNativeScreens: false,
  screens: {
    Home: HomeScreen,
    Detail: DetailScreen,
  },
});
```

--------------------------------

### Gesture Configuration Options

Source: https://screen-transitions.esjr.org/gestures

A collection of properties used to configure gesture behavior, sensitivity, and custom rendering components for screens.

```APIDOC
## Gesture Configuration Properties

### gestureEnabled
- **Type**: `boolean`
- **Default**: `undefined`
- **Description**: Enables swipe-to-dismiss.

### gestureDirection
- **Type**: `GestureDirectionEntry | GestureDirectionEntry[]`
- **Default**: `"horizontal"`
- **Description**: Dismiss direction, pan axis, pinch direction, or ordered direction list.

### gestureTracking
- **Type**: `"auto" | "never" | "always"`
- **Default**: `"auto"`
- **Description**: Controls whether the screen tracks live gesture values.

### gestureSensitivity
- **Type**: `number`
- **Default**: `1`
- **Description**: Multiplies live gesture movement before it drives progress.

### gestureVelocityImpact
- **Type**: `number`
- **Default**: `0.3`
- **Description**: Release velocity influence on dismiss decisions.

### gestureSnapVelocityImpact
- **Type**: `number`
- **Default**: `0.1`
- **Description**: Release velocity influence on snap-target selection.

### gestureSnapLocked
- **Type**: `boolean`
- **Default**: `false`
- **Description**: Locks gesture-driven snap movement to the current detent.

### gestureReleaseVelocityScale
- **Type**: `number`
- **Default**: `1`
- **Description**: Multiplies normalized release velocity before the spring runs.

### sheetScrollGestureBehavior
- **Type**: `"expand-and-collapse" | "collapse-only"`
- **Default**: `"expand-and-collapse"`
- **Description**: Scroll-boundary handoff mode for snap sheets.

### backdropBehavior
- **Type**: `"block" | "passthrough" | "dismiss" | "collapse"`
- **Default**: `stack default`
- **Description**: Controls how taps on the backdrop are handled.

### backdropComponent
- **Type**: `React.ComponentType<any> | ScreenBackdropComponent`
- **Default**: `undefined`
- **Description**: Custom backdrop component type.

### contentComponent
- **Type**: `React.ComponentType<any> | ScreenContentComponent`
- **Default**: `undefined`
- **Description**: Custom renderer for the screen content layer.
```

--------------------------------

### Stack.Screen Gesture Configuration

Source: https://screen-transitions.esjr.org/gestures

Configuring gesture settings within the Stack.Screen options component.

```APIDOC
## Stack.Screen Gesture Configuration

### Description
Configures gesture-based dismissal and interaction settings for a screen within a stack navigator.

### Parameters
- **gestureEnabled** (boolean) - Optional - Enables or disables gesture-based dismissal.
- **gestureDirection** (string | array | object) - Optional - Defines the allowed pan and pinch directions for gestures. Supported values include "horizontal", "horizontal-inverted", "vertical", "vertical-inverted", "bidirectional", "pinch-in", "pinch-out", or structured objects with { gesture, area }.

### Example
```tsx
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    gestureEnabled: true,
    gestureDirection: "vertical",
  }}
/>
```
```

--------------------------------

### Implement Stack-wide Overlay

Source: https://screen-transitions.esjr.org/overlays

Apply the same overlay component across multiple screens in a navigator to maintain persistence.

```TSX
<Stack.Navigator>
  <Stack.Screen
    name="index"
    component={IndexScreen}
    options={{
      overlay: TabBarOverlay,
      overlayShown: true,
    }}
  />

  <Stack.Screen
    name="second"
    component={SecondScreen}
    options={{
      overlay: TabBarOverlay,
      overlayShown: true,
    }}
  />

  <Stack.Screen
    name="third"
    component={ThirdScreen}
    options={{
      overlay: TabBarOverlay,
      overlayShown: true,
    }}
  />
</Stack.Navigator>
```

--------------------------------

### Configure basic screen gestures

Source: https://screen-transitions.esjr.org/gestures

Enable and define the gesture direction for a screen within the Stack.Screen options.

```TSX
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    gestureEnabled: true,
    gestureDirection: "vertical",
    screenStyleInterpolator,
  }}
/>
```

--------------------------------

### Implementing navigation.zoom() in screen options

Source: https://screen-transitions.esjr.org/navigation-zoom

Configure the destination screen's screenStyleInterpolator to use navigation.zoom() and provide the active boundary ID.

```tsx
import { makeMutable } from "react-native-reanimated";

const navigationZoomId = makeMutable<string | null>(null);

<Transition.Boundary
  id={item.id}
  onPress={() => {
    navigationZoomId.value = item.id;
    navigation.navigate("Detail");
  }}
>
  <Image source={item.image} style={styles.artwork} />
</Transition.Boundary>

<Stack.Screen
  name="[id]"
  options={{
    navigationMaskEnabled: Platform.OS === "ios",
    gestureEnabled: true,
    gestureDirection: ["vertical", "vertical-inverted", "horizontal"],
    transitionSpec: Transition.Specs.Zoom,
    screenStyleInterpolator: ({ bounds }) => {
      "worklet";
      const id = navigationZoomId.value;

      if (!id) {
        return null;
      }

      return bounds(id).navigation.zoom({
        borderRadius: 48,
      });
    },
  }}
/>
```

--------------------------------

### content

Source: https://screen-transitions.esjr.org/surface-slots

Targets the root animated container for the screen itself, used for main screen motion like translate, scale, and opacity.

```APIDOC
## content

### Description
Targets the root animated container for the screen itself. This slot usually carries the main screen motion such as translate, scale, opacity, rotation, and overall clipping styles.

### Configuration
- **content** (object) - Defines the style and animation logic for the screen content container.
- **contentComponent** (function) - A custom shell component for the content layer. Receives `styles`, `props`, `pointerEvents`, and `children` as render props.
```

--------------------------------

### navigation.zoom()

Source: https://screen-transitions.esjr.org/navigation-zoom

Initiates a zoom transition from a source element to a destination. The method accepts a configuration object to customize the animation's appearance and drag response.

```APIDOC
## navigation.zoom(options)

### Description
Triggers a zoom transition. This method can be used for list-to-detail flows by defining a source boundary and optional configuration parameters.

### Parameters
#### Options
- **target** ("bound" | "fullscreen" | MeasuredDimensions) - Optional - Defines the zoom target. Defaults to a full-width rectangle preserving the source aspect ratio.
- **keepFocusedVisible** (boolean) - Optional - If true, keeps focused content visible. Defaults to false.
- **borderRadius** (number) - Optional - The expanded clipping radius. Defaults to 64.
- **backgroundScale** (number) - Optional - Scale applied to the unfocused screen. Defaults to 0.9375.
- **backdropColor** (ColorValue) - Optional - Color behind the focused zoom content. Defaults to "black".
- **backdropOpacity** (number) - Optional - Maximum backdrop opacity (0-1). Defaults to 0.45.
- **drag.translation.horizontal** (number) - Optional - Horizontal rendered-translation response. Defaults to 1.
- **drag.translation.vertical** (number) - Optional - Vertical rendered-translation response. Defaults to 1.
- **drag.scale.horizontal** (number) - Optional - Horizontal drag-scale response. Defaults to 1.
- **drag.scale.vertical** (number) - Optional - Vertical drag-scale response. Defaults to 1.

### Request Example
```javascript
return bounds(id).navigation.zoom({
  borderRadius: 48,
  target: "bound",
  backgroundScale: 0.96,
  backdropColor: "#000",
  backdropOpacity: 0.45,
  drag: {
    translation: { horizontal: 0.9, vertical: 0.85 },
    scale: { horizontal: 1, vertical: 0.8 },
  },
});
```
```

--------------------------------

### Configure Reveal Gesture Options

Source: https://screen-transitions.esjr.org/reveal

Enables gesture-based navigation with specified directions for the reveal transition.

```tsx
options={{
  gestureEnabled: true,
  gestureDirection: ["vertical", "horizontal"],
}}
```

--------------------------------

### Implement Transition.Boundary

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Use the unified Transition.Boundary component for both pressable and passive boundaries. The onPress prop determines whether the boundary acts as a trigger.

```tsx
<Transition.Boundary
  id="cover"
  onPress={() => navigation.push("Details")}
>
  <Transition.Boundary.Target style={styles.cover}>
    <Image source={cover} style={styles.image} />
  </Transition.Boundary.Target>
</Transition.Boundary>
```

```tsx
// Passive boundary
<Transition.Boundary id="avatar">
  <Image source={avatar} style={styles.avatar} />
</Transition.Boundary>

// Pressable boundary
<Transition.Boundary
  id="avatar"
  onPress={() => navigation.push("Profile")}
>
  <Image source={avatar} style={styles.avatar} />
</Transition.Boundary>
```

--------------------------------

### Create Custom Overlay Component

Source: https://screen-transitions.esjr.org/overlays

Build an overlay component using OverlayProps and useScreenAnimation to react to stack progress.

```TSX
import Animated, {
  interpolate,
  useAnimatedStyle,
} from "react-native-reanimated";
import {
  type OverlayProps,
  useScreenAnimation,
} from "react-native-screen-transitions";

function TabBarOverlay({
  focusedRoute,
  focusedIndex,
  routes,
  navigation,
}: OverlayProps) {
  const animation = useScreenAnimation();

  const style = useAnimatedStyle(() => {
    const { stackProgress } = animation.value;

    return {
      opacity: interpolate(stackProgress, [1, 2], [1, 0.3], "clamp"),
    };
  });

  return (
    <Animated.View style={style}>
      <Text>{focusedRoute.name}</Text>
      <Text>
        {focusedIndex + 1} / {routes.length}
      </Text>
    </Animated.View>
  );
}
```

--------------------------------

### Launcher Screen Implementation

Source: https://screen-transitions.esjr.org/recipes/modal

Uses expo-router to push a modal route from the main index screen.

```tsx
1import { router } from "expo-router";
2import { Button, View } from "react-native";
3import { useTheme } from "@/theme";
4
5export default function ExampleIndex() {
6  const theme = useTheme();
7
8  return (
9    <View
10      style={{
11        flex: 1,
12        alignItems: "center",
13        justifyContent: "center",
14        backgroundColor: theme.bg,
15      }}
16    >
17      <Button title="Open Modal" onPress={() => router.push("/example/modal")} />
18    </View>
19  );
20}
```

--------------------------------

### Implement Boundary Pattern for Screen Transitions

Source: https://screen-transitions.esjr.org/shared-elements

Use Transition.Boundary to define source and destination elements for geometry synchronization. The component acts as a pressable source when onPress is provided and a passive measured view otherwise.

```TSX
1// Source screen
2<Transition.Boundary
3  id="hero"
4  onPress={() => navigation.navigate("Detail")}
5>
6  <Image source={heroImage} style={{ width: 120, height: 160 }} />
7</Transition.Boundary>
8
9// Destination screen
10<Transition.Boundary id="hero">
11  <Image source={heroImage} style={{ width: "100%", height: 360 }} />
12</Transition.Boundary>
```

--------------------------------

### Configure Reveal Background Scaling

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-7

Adjust background scaling parameters during a reveal transition.

```tsx
return bounds({ id }).navigation.reveal({
  backgroundScale: 0.96,
  shouldBackgroundScaleResetOnSettled: true,
});
```

--------------------------------

### blockTransition(routeKey?: string)

Source: https://screen-transitions.esjr.org/transition-components

Holds a screen's pending lifecycle transition at its initial frame. This is reference-counted per route.

```APIDOC
## blockTransition(routeKey?: string)

### Description
Blocks the transition of a screen, holding it at its initial frame. This is useful for delaying visual transitions until the destination screen has finished preparing.

### Parameters
- **routeKey** (string) - Optional - The unique key of the route to block. If omitted, the most recently focused screen in navigation history is used.
```

--------------------------------

### Configure surface component options

Source: https://screen-transitions.esjr.org/surface-slots

Use the surface key to style the wrapper created by the deprecated surfaceComponent.

```TSX
options={{
  surfaceComponent: SquircleView,
}}

surface: {
  style: {
    borderRadius: interpolate(progress, [0, 1], [28, 0]),
  },
  props: {
    cornerRadius: interpolate(progress, [0, 1], [28, 0]),
  },
}
```

--------------------------------

### Implement Transition Boundaries

Source: https://screen-transitions.esjr.org/changelog/migrating-to-3-4

Use Transition.Boundary components to define trigger and view relationships for screen transitions.

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

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

--------------------------------

### Configure VideoView for Boundary Handoff

Source: https://screen-transitions.esjr.org/caveats

Use textureView for VideoView when content must clip or animate with a boundary to avoid SurfaceView rendering issues.

```tsx
<VideoView
  player={player}
  surfaceType="textureView"
  style={StyleSheet.absoluteFill}
/>
```

--------------------------------

### Stack.Screen Options: snapPoints

Source: https://screen-transitions.esjr.org/snap-points

Configures a screen to behave as a detented sheet using snapPoints and initialSnapIndex.

```APIDOC
## Stack.Screen Options

### Description
Defines the behavior of a screen as a detented sheet or drawer.

### Properties
- **snapPoints** (Array<number | "auto">) - Required - An array of values in ascending order representing fractions of the screen size or "auto" for intrinsic content sizing.
- **initialSnapIndex** (number) - Optional - The index of the snap point at which the screen initially opens.
- **gestureEnabled** (boolean) - Optional - Controls whether the sheet can be dismissed past its minimum detent.

### Example
```tsx
<Stack.Screen
  name="sheet"
  component={SheetScreen}
  options={{
    gestureEnabled: true,
    gestureDirection: "vertical",
    snapPoints: [0.4, 0.7, 1],
    initialSnapIndex: 0,
  }}
/>
```
```

--------------------------------

### Configure Bounds-Driven Transitions

Source: https://screen-transitions.esjr.org/quick-start

Connects elements between screens using Transition.Boundary and enables navigation masking for zoom transitions.

```typescript
// Home screen
<Transition.Boundary
id="hero"
onPress={() => navigation.navigate("Detail")}
>
<Image source={heroImage} style={{ width: 120, height: 160 }} />
</Transition.Boundary>

// Detail screen
<Transition.Boundary id="hero">
<Image source={heroImage} style={{ width: "100%", height: 360 }} />
</Transition.Boundary>
```

```typescript
<Stack.Screen
name="Detail"
component={DetailScreen}
options={{
  navigationMaskEnabled: true,
  transitionSpec: Transition.Specs.Zoom,
  screenStyleInterpolator: ({ bounds }) => {
    "worklet";
    return bounds("hero").navigation.zoom();
  },
}}
/>
```

--------------------------------

### Using the Scoped Bounds API

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Demonstrates the basic usage of the new scoped bounds accessor within a worklet.

```TSX
1screenStyleInterpolator: ({ bounds }) => {
2  "worklet";
3
4  return {
5    cover: {
6      style: bounds("cover").styles({
7        offset: { y: -12 },
8      }),
9    },
10  };
11};
```

--------------------------------

### Configure Source Boundary

Source: https://screen-transitions.esjr.org/reveal

Wrap the source element in a Transition.Boundary and pass the reveal ID through navigation parameters.

```TSX
import Transition from "react-native-screen-transitions";

<Transition.Boundary
  id={item.id}
  onPress={() => {
    navigation.navigate("Detail", { revealId: item.id });
  }}
>
  <Image source={item.image} style={styles.thumbnail} />
</Transition.Boundary>
```

--------------------------------

### Configuring Gesture Relations

Source: https://screen-transitions.esjr.org/gestures

Shows how to use a parent gesture ref to define external gesture requirements for a pan gesture.

```TSX
const parentGestureRef = useScreenGesture({ depth: -1 });

const customPan = Gesture.Pan().requireExternalGestureToFail(parentGestureRef);
```

--------------------------------

### createTransitionAwareComponent(component, options)

Source: https://screen-transitions.esjr.org/api/create-transition-aware-component

Wraps a custom component to enable styleId support and transition measurement participation.

```APIDOC
## createTransitionAwareComponent(component, options)

### Description
Wraps a custom component so it can receive `styleId` styles and participate in transition measurement. When `isScrollable` is enabled, it coordinates gestures and publishes scroll metadata.

### Parameters
- **component** (Component) - Required - The custom component to be wrapped.
- **options** (Object) - Optional - Configuration options for the component.

#### Options
- **alreadyAnimated** (boolean) - Optional - Set `true` when the wrapped component is already animated.
- **isScrollable** (boolean) - Optional - Set `true` for custom scrollables that should coordinate gestures and publish `layouts.scroll` metadata.

### Usage Example
```tsx
import Transition from "react-native-screen-transitions";

const TransitionBlurView = Transition.createTransitionAwareComponent(BlurView, {
	alreadyAnimated: false,
});

<TransitionBlurView styleId="blur" intensity={40} />;
```
```

--------------------------------

### bounds().styles()

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Configures motion interpolation for a specific element during a transition.

```APIDOC
## bounds().styles(options)

### Description
Applies a motion resolver to customize the path between start and end bounds.

### Parameters
- **motion** (function) - Required - A resolver function receiving { current, progress, start, end, props } and returning a transform object.

### Motion Resolver Arguments
- **current** (object) - The generated bounds transform for the current frame.
- **progress** (number) - Normalized progress from 0 to 1.
- **start** (object) - The resolved source rect.
- **end** (object) - The resolved destination rect.
- **props** (object) - The active interpolation props.

### Supported Return Fields
- **x** (number)
- **y** (number)
- **scale** (number)
- **rotate** (number)
- **rotateX** (number)
- **rotateY** (number)
- **perspective** (number)
- **transformOrigin** (string)
```

--------------------------------

### createTransitionAwareComponent

Source: https://screen-transitions.esjr.org/api

A factory for creating components that are aware of transitions.

```APIDOC
## createTransitionAwareComponent

### Description
A factory function that wraps a component to make it aware of screen transition states.
```

--------------------------------

### Transition.Boundary

Source: https://screen-transitions.esjr.org/transition-components

The primary component for bounds-driven transitions, supporting both passive and pressable registration.

```APIDOC
## Transition.Boundary

### Description
Registers a component as a boundary for transitions. If `onPress` is provided, it acts as a pressable boundary; otherwise, it is a passive view.

### Props
- **id** (string) - Required - Unique identifier for the boundary.
- **onPress** (function) - Optional - Callback for interaction.
- **group** (string) - Optional - Grouping identifier.
- **anchor** (string) - Optional - Anchor configuration.
- **scaleMode** (string) - Optional - Scaling behavior.
- **target** (string) - Optional - Target configuration.
- **method** (string) - Optional - Transition method.
- **enabled** (boolean) - Optional - Toggle boundary state.
- **handoff** (boolean) - Optional - Enable handoff.
- **escapeClipping** (boolean) - Optional - Allow clipping escape.
```

--------------------------------

### Transition Primitives

Source: https://screen-transitions.esjr.org/transition-components

Transition-aware wrappers for standard React Native components that support slot-driven styles and bounds measurement.

```APIDOC
## Transition Primitives

### Description
Wrappers for standard React Native components that participate in transition animations and layout measurements.

### Components
- **Transition.View**: For non-pressable elements.
- **Transition.Pressable**: For interactive elements.
- **Transition.ScrollView**: For scrollable content that publishes scroll metadata.
- **Transition.FlatList**: For list content with gesture-aware scroll behavior.

### Common Props
- **styleId** (string) - Used for element targeting from `screenStyleInterpolator`.
```

--------------------------------

### bounds(id).navigation.reveal()

Source: https://screen-transitions.esjr.org/reveal

Configures a reveal transition within a screen style interpolator, typically used for card or media-detail flows.

```APIDOC
## bounds(id).navigation.reveal()

### Description
Configures the reveal transition animation for a navigation screen. This method scales and masks the destination content from the source boundary into the destination container.

### Parameters
- **borderRadius** (number) - Optional - The border radius applied to the revealed element.
- **borderContinuous** (boolean) - Optional - Whether to use continuous corner curves.
- **maxSensitivity** (number) - Optional - Controls the sensitivity of the transition interaction.
- **velocityDepth** (number) - Optional - Adjusts the depth effect based on gesture velocity.

### Usage Example
```javascript
return bounds(id).navigation.reveal({
  borderRadius: 58,
  borderContinuous: true,
  maxSensitivity: 0.8,
  velocityDepth: 0.5,
});
```
```

--------------------------------

### Using bounds() in screenStyleInterpolator

Source: https://screen-transitions.esjr.org/shared-elements

Demonstrates how to use the bounds accessor within a screenStyleInterpolator to apply animated styles to a hero element.

```TSX
screenStyleInterpolator: ({ bounds, progress, focused }) => {
  "worklet";

  return {
    hero: {
      style: {
        ...bounds("hero").styles({
          method: "transform",
        }),
        opacity: focused
          ? interpolate(progress, [0, 1], [0, 1], "clamp")
          : interpolate(progress, [1, 2], [1, 0], "clamp"),
      },
    },
  };
};
```

--------------------------------

### withScreenTransitions

Source: https://screen-transitions.esjr.org/adapters

Wraps an existing navigator to make its screens transition-aware. This is useful for apps that rely on native-stack behavior but require custom screen transitions for specific screens.

```APIDOC
## withScreenTransitions(navigator)

### Description
Wraps a React Navigation native-stack navigator to enable custom screen transitions. Use this when you need to maintain native-stack behavior while adding transition support to specific screens.

### Parameters
- **navigator** (Object) - Required - The native stack navigator instance created via `createNativeStackNavigator`.

### Usage Example
```tsx
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import Transition, { withScreenTransitions } from "react-native-screen-transitions";

const NativeStack = createNativeStackNavigator();
const Stack = withScreenTransitions(NativeStack);
```

### Screen Configuration
To enable transitions on a specific screen, set `enableTransitions: true` in the screen options:
```tsx
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    enableTransitions: true,
    gestureEnabled: true,
    transitionSpec: {
      open: Transition.Specs.DefaultSpec,
      close: Transition.Specs.DefaultSpec,
    }
  }}
/>
```
```

--------------------------------

### Using a Custom Progress Driver

Source: https://screen-transitions.esjr.org/shared-elements

Pass transitionProgress to keep geometry on the committed transition path while layering gesture motion separately.

```TSX
screenStyleInterpolator: ({ bounds, current }) => {
  "worklet";

  return {
    hero: {
      style: bounds("hero").styles({
        progress: current.transitionProgress,
        offset: {
          x: current.gesture.x,
          y: current.gesture.y,
        },
      }),
    },
  };
};
```

--------------------------------

### Configure Independent BlankStack

Source: https://screen-transitions.esjr.org/expo-router

Create an isolated navigation tree using the independent prop.

```tsx
<BlankStack independent enableNativeScreens={false}>
  <BlankStack.Screen name="index" />
</BlankStack>
```

--------------------------------

### Set Content Component Options

Source: https://screen-transitions.esjr.org/surface-slots

Configures a custom shell component for the screen content layer.

```TSX
1options={{
2  contentComponent: ({ styles, props, pointerEvents, children }) => (
3    <Animated.View
4      style={styles}
5      animatedProps={props}
6      pointerEvents={pointerEvents}
7    >
8      {children}
9    </Animated.View>
10  ),
11}}
```

--------------------------------

### useHistory()

Source: https://screen-transitions.esjr.org/api/use-history

Subscribes to the stack history store and returns an object with methods to query navigation history.

```APIDOC
## useHistory()

### Description
Subscribes to the stack history store and provides methods to access navigation history entries.

### Returns
- **history** (Map) - Read-only map of screen keys to history entries.
- **getRecent(n)** (Function) - Returns the most recent `n` entries, ordered newest first.
- **getByNavigator(key)** (Function) - Returns entries for a specific navigator, ordered newest first.
- **getPath(fromKey, toKey)** (Function) - Returns screen keys between two history entries.
- **get(key)** (Function) - Returns a single history entry by screen key.
- **getMostRecent()** (Function) - Returns the latest history entry.

### Usage Example
```tsx
import { useHistory } from "react-native-screen-transitions";

const history = useHistory();
const latest = history.getMostRecent();
const recent = history.getRecent(3);
```
```

--------------------------------

### Transition.View usage

Source: https://screen-transitions.esjr.org/transition-components

Use for non-pressable elements that require transition-aware styling.

```TSX
1<Transition.View styleId="hero-title">
2  <Text>Title</Text>
3</Transition.View>
```

--------------------------------

### Configure Screen Transition with Zoom Spec

Source: https://screen-transitions.esjr.org/transition-components

Applies a zoom transition specification and custom style interpolator to a navigation screen.

```tsx
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    transitionSpec: Transition.Specs.Zoom,
    screenStyleInterpolator: ({ bounds }) => {
      "worklet";
      return bounds("hero").navigation.zoom();
    },
  }}
/>
```

--------------------------------

### surface

Source: https://screen-transitions.esjr.org/surface-slots

Configures the optional wrapper for surfaceComponent. Note that surfaceComponent is deprecated in favor of contentComponent.

```APIDOC
## surface

### Description
Targets the optional wrapper created by `surfaceComponent`. This is intended for legacy code compatibility.

### Configuration
- **style** (object) - Style properties for the surface wrapper.
- **props** (object) - Props to be passed to the surface component.
```

--------------------------------

### Transition.Boundary.Host usage

Source: https://screen-transitions.esjr.org/transition-components

Use to define an explicit coordinate space for handoff or clipping-escape placement.

```TSX
1<Transition.ScrollView>
2  <Transition.Boundary.Host />
3
4  <Transition.Boundary id="card" escapeClipping onPress={openCard}>
5    <Image source={image} style={styles.card} />
6  </Transition.Boundary>
7</Transition.ScrollView>
```

--------------------------------

### Configure navigation zoom

Source: https://screen-transitions.esjr.org/changelog/updating-to-3-9

Use navigation.zoom() to control appearance and drag-response settings for screen transitions.

```TSX
return bounds(id).navigation.zoom({
  target: "bound",
  keepFocusedVisible: true,
  borderRadius: 48,
  backgroundScale: 0.95,
  backdropColor: "#000",
  backdropOpacity: 0.4,
  drag: {
    translation: { horizontal: 0.9, vertical: 0.85 },
    scale: { horizontal: 1, vertical: 0.8 },
  },
});
```

--------------------------------

### Implement Navigation Interpolator

Source: https://screen-transitions.esjr.org/reveal

Enable navigationMaskEnabled and call navigation.reveal() within the screenStyleInterpolator.

```TSX
<Stack.Screen
  name="Detail"
  component={DetailScreen}
  options={{
    navigationMaskEnabled: true,
    gestureEnabled: true,
    gestureDirection: ["vertical", "horizontal"],
    screenStyleInterpolator: ({ active, bounds }) => {
      "worklet";

      const id = active.route.params?.revealId;
      if (!id) return null;

      return bounds(id).navigation.reveal({
        borderRadius: 58,
        borderContinuous: true,
        maxSensitivity: 0.8,
        velocityDepth: 0.5,
      });
    },
  }}
/>
```

--------------------------------

### Implement Parent Layout with Gesture Tracking

Source: https://screen-transitions.esjr.org/recipes/modal

Configures the modal transition with custom interpolation to handle gesture sensitivity and release velocity based on the current screen's gestureEnabled option.

```typescript
1import { interpolate } from "react-native-reanimated";
2import type { ScreenTransitionConfig } from "react-native-screen-transitions";
3import Transition from "react-native-screen-transitions";
4import { BlankStack } from "@/layouts/blank-stack";
5
6const modalOptions: ScreenTransitionConfig = {
7  gestureEnabled: true,
8  gestureTracking: "always",
9  gestureDirection: "vertical",
10  screenStyleInterpolator: ({
11    layouts: {
12      screen: { height },
13    },
14    progress,
15    focused,
16    active,
17    current,
18  }) => {
19    "worklet";
20
21    const isGestureDisabled = !current.options.gestureEnabled;
22
23    const translateY = focused
24      ? interpolate(progress, [0, 1], [height, 0], "clamp")
25      : 0;
26
27    const gestureSensitivity = isGestureDisabled
28      ? interpolate(progress, [0, 0.25], [1, 0.1], "clamp")
29      : 1;
30
31    const gestureReleaseVelocityScale = isGestureDisabled ? 0 : 1;
32
33    const contentStyle = {
34      transform: [{ translateY }],
35      maxHeight: focused ? height * 0.9 : undefined,
36      marginTop: focused ? "auto" : undefined,
37    } as const;
38
39    const backdropStyle = focused
40      ? {
41          backgroundColor: "#00000050",
42          opacity: active.progress,
43        }
44      : undefined;
45
46    return {
47      options: {
48        gestureSensitivity,
49        gestureReleaseVelocityScale,
50      },
51      content: { style: contentStyle },
52      backdrop: { style: backdropStyle },
53    };
54  },
55  transitionSpec: {
56    open: Transition.Specs.DefaultSpec,
57    close: Transition.Specs.DefaultSpec,
58  },
59};
60
61export default function ExampleLayout() {
62  return (
63    <BlankStack>
64      <BlankStack.Screen name="index" />
65      <BlankStack.Screen name="modal" options={modalOptions} />
66    </BlankStack>
67  );
68}
```

--------------------------------

### createBoundaryComponent()

Source: https://screen-transitions.esjr.org/api/create-boundary-component

Wraps a custom component with the boundary system to enable transition boundary behavior.

```APIDOC
## createBoundaryComponent()

### Description
Wraps a custom component with the boundary system. Use this when a custom component should behave like `Transition.Boundary` without adding an extra wrapper view around it.

### Signature
`createBoundaryComponent(Component, options)`

### Parameters
- **Component** (Component) - The custom component to wrap.
- **options** (Object) - Configuration options for the boundary.
  - **alreadyAnimated** (boolean) - Optional - Specifies if the component is already animated.

### Boundary Props
The wrapped component accepts the following boundary props:
- **id** (string)
- **group** (string)
- **anchor** (string)
- **scaleMode** (string)
- **target** (string)
- **method** (string)
- **enabled** (boolean)
- **handoff** (boolean)
- **escapeClipping** (boolean)

### Example
```tsx
import Transition from "react-native-screen-transitions";

const BoundaryImage = Transition.createBoundaryComponent(Image, {
	alreadyAnimated: false,
});

<BoundaryImage id="avatar" source={avatar} style={styles.avatar} />
```
```

--------------------------------

### createBoundaryComponent

Source: https://screen-transitions.esjr.org/api

A factory for creating boundary components.

```APIDOC
## createBoundaryComponent

### Description
A factory function used to create a boundary component for managing transition scopes.
```

--------------------------------

### Configure native screen rendering

Source: https://screen-transitions.esjr.org/independent-stacks

Set enableNativeScreens to false to render the stack using regular views instead of native screen primitives.

```TSX
const Stack = createBlankStackNavigator();

<Stack.Navigator enableNativeScreens={false}>
  <Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
```

--------------------------------

### Transition.FlatList usage

Source: https://screen-transitions.esjr.org/transition-components

Use for list content to enable gesture-aware scroll behavior.

```TSX
1<Transition.FlatList
2  data={items}
3  renderItem={renderItem}
4  keyExtractor={(item) => item.id}
5/>
```
Tokens:
Raw