Overlays | Screen Transitions

Mental Model

An overlay is a floating screen layer owned by a screen in a stack.

Configure it on screen options with overlay and overlayShown.

TSX

1<Stack.Screen
2  name="index"
3  component={HomeScreen}
4  options={{
5    overlay: TabBarOverlay,
6    overlayShown: true,
7  }}
8/>

The overlay belongs to the screen that defines it, not the whole app.

How Overlay Ownership Works

An overlay starts floating when its owner screen becomes active and stays active while you push screens above that owner.

if index defines an overlay, it can float from index through the rest of the stack
if screen 3 defines an overlay, it does not appear on screens 1 or 2
once you reach screen 3, that overlay can float from screen 3 through any screens above it
if a higher screen defines a visible overlay, that higher screen becomes the new overlay owner

This is stack-relative, not a global portal.

Basic Example

TSX

1<Stack.Navigator>
2  <Stack.Screen
3    name="index"
4    component={IndexScreen}
5    options={{
6      overlay: TabBarOverlay,
7      overlayShown: true,
8    }}
9  />
10
11  <Stack.Screen
12    name="second"
13    component={SecondScreen}
14    options={{
15      overlay: TabBarOverlay,
16      overlayShown: true,
17    }}
18  />
19
20  <Stack.Screen
21    name="third"
22    component={ThirdScreen}
23    options={{
24      overlay: TabBarOverlay,
25      overlayShown: true,
26    }}
27  />
28</Stack.Navigator>

The same overlay can keep floating deeper through the stack.

If you push a screen with overlayShown: false, the system skips that screen and keeps scanning downward for the highest visible overlay owner.

Overlay Component Example

TSX

1import Animated, {
2  interpolate,
3  useAnimatedStyle,
4} from "react-native-reanimated";
5import {
6  type OverlayProps,
7  useScreenAnimation,
8} from "react-native-screen-transitions";
9
10function TabBarOverlay({
11  focusedRoute,
12  focusedIndex,
13  routes,
14  navigation,
15}: OverlayProps) {
16  const animation = useScreenAnimation();
17
18  const style = useAnimatedStyle(() => {
19    const { stackProgress } = animation.value;
20
21    return {
22      opacity: interpolate(stackProgress, [1, 2], [1, 0.3], "clamp"),
23    };
24  });
25
26  return (
27    <Animated.View style={style}>
28      <Text>{focusedRoute.name}</Text>
29      <Text>
30        {focusedIndex + 1} / {routes.length}
31      </Text>
32    </Animated.View>
33  );
34}

stackProgress is relative to the overlay owner's position in the stack.

Overlay Props

Prop	Purpose
`focusedRoute`	Focused route in the current stack
`focusedIndex`	Focused route index
`routes`	All routes in the current stack
`meta`	`meta` from the focused screen options
`navigation`	Navigation object for the overlay's owning stack
`options`	Focused screen transition options
`progress`	Overlay-relative stack progress

Many overlay components read animation state through useScreenAnimation() instead of consuming progress directly.