Learn how to use the Stack navigator in Expo Router.
A stack navigator is the foundational way of navigating between routes in an app. On Android, a stacked route animates on top of the current screen. On iOS, a stacked route animates from the right. Expo Router provides a Stack navigation component that creates a navigation stack and allows you to add new routes in your app.
This guide provides information on how you can create a Stack navigator in your project and customize an individual route's options and header.
You can use file-based routing to create a stack navigator. Here's an example file structure:
app_layout.tsxindex.tsxdetails.tsxThis file structure produces a layout where the index route is the first route in the stack, and the details route is pushed on top of the index route when navigated.
You can use the app/_layout.tsx file to define your app's Stack navigator with these two routes:
import { Stack } from 'expo-router/stack';
export default function Layout() {
return <Stack />;
}
You can use the <Stack.Screen name={routeName} /> component in the layout component route to statically configure a route's options. This is also useful for tabs or drawers as they need an icon defined ahead of time.
import { Stack } from 'expo-router';
export default function Layout() {
return (
<Stack
screenOptions={{
headerStyle: {
backgroundColor: '#f4511e',
},
headerTintColor: '#fff',
headerTitleStyle: {
fontWeight: 'bold',
},
}}>
{/* Optionally configure static options outside the route.*/}
<Stack.Screen name="home" options={{}} />
</Stack>
);
}
As an alternative to the <Stack.Screen> component, you can use navigation.setOptions() to configure a route's options from within the route's component file.
import { Stack, useNavigation } from 'expo-router';
import { Text, View } from 'react-native';
import { useEffect } from 'react';
export default function Home() {
const navigation = useNavigation();
useEffect(() => {
navigation.setOptions({ headerShown: false });
}, [navigation]);
return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
</View>
);
}
You can configure the header bar for all routes in a Stack navigator by using the screenOptions prop. This is useful for setting a common header style across all routes.
import { Stack } from 'expo-router';
export default function Layout() {
return (
<Stack
screenOptions={{
headerStyle: {
backgroundColor: '#f4511e',
},
headerTintColor: '#fff',
headerTitleStyle: {
fontWeight: 'bold',
},
}}
/>
);
}
To configure the header bar dynamically for an individual route, use that navigator's <Stack.Screen> component in the routes's file. This is useful for interactions that change the UI.
import { Link, Stack } from 'expo-router';
import { Image, Text, View, StyleSheet } from 'react-native';
function LogoTitle() {
return (
<Image style={styles.image} source={{ uri: 'https://reactnative.dev/img/tiny_logo.png' }} />
);
}
export default function Home() {
return (
<View style={styles.container}>
<Stack.Screen
options={{
title: 'My home',
headerStyle: { backgroundColor: '#f4511e' },
headerTintColor: '#fff',
headerTitleStyle: {
fontWeight: 'bold',
},
headerTitle: props => <LogoTitle {...props} />,
}}
/>
<Text>Home Screen</Text>
<Link href={{ pathname: 'details', params: { name: 'Bacon' } }}>Go to Details</Link>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
image: {
width: 50,
height: 50,
},
});
To configure a route's option dynamically, you can always use the <Stack.Screen> component in that route's file.
As an alternative, you can also use the imperative API's router.setParams() function to configure the route dynamically.
import { Stack, useLocalSearchParams, useRouter } from 'expo-router';
import { View, Text, StyleSheet } from 'react-native';
export default function Details() {
const router = useRouter();
const params = useLocalSearchParams();
return (
<View style={styles.container}>
<Stack.Screen
options={{
title: params.name,
}}
/>
<Text
onPress={() => {
router.setParams({ name: 'Updated' });
}}>
Update the title
</Text>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
});
You can add buttons to the header by using the headerLeft and headerRight options. These options accept a React component that renders in the header.
import { Stack } from 'expo-router';
import { Button, Text, Image, StyleSheet } from 'react-native';
import { useState } from 'react';
function LogoTitle() {
return (
<Image style={styles.image} source={{ uri: 'https://reactnative.dev/img/tiny_logo.png' }} />
);
}
export default function Home() {
const [count, setCount] = useState(0);
return (
<>
<Stack.Screen
options={{
headerTitle: props => <LogoTitle {...props} />,
headerRight: () => <Button onPress={() => setCount(c => c + 1)} title="Update count" />,
}}
/>
<Text>Count: {count}</Text>
</>
);
}
const styles = StyleSheet.create({
image: {
width: 50,
height: 50,
},
});
By default, the Stack navigator removes duplicate screens when pushing a route that is already in the stack. For example, if you push the same screen twice, the second push will be ignored. You can change this push behavior by providing a custom getId() function to the <Stack.Screen>.
For example, the index route in the following layout structure shows a list of different user profiles in the app. Let's make the [details] route a dynamic route so that the app user can navigate to see a profile's details.
app_layout.tsxindex.tsx[details].tsxmatches dynamic paths like '/details1'The Stack navigator will push a new screen every time the app user navigates to a different profile but will fail. If you provide a getId() function that returns a new ID every time, the Stack will push a new screen every time the app user navigates to a profile.
You can use the <Stack.Screen name="[profile]" getId={}> component in the layout component route to modify the push behavior:
import { Stack } from 'expo-router';
export default function Layout() {
return (
<Stack>
<Stack.Screen
name="[profile]"
getId={
({ params }) =>
String(Date.now())
}
/>
</Stack>
);
}
There are different actions you can use to dismiss and remove one or many routes from a stack.
dismiss actionDismisses the last screen in the closest stack. If the current screen is the only route in the stack, it will dismiss the entire stack.
You can optionally pass a positive number to dismiss up to that specified number of screens.
Dismiss is different from back as it targets the closest stack and not the current navigator. If you have nested navigators, calling dismiss will take you back multiple screens.
import { Button, View, Text } from "react-native";
import { useRouter } from "expo-router";
export default function Settings() {
const router = useRouter();
const handleDismiss = (count) => {
router.dismiss(count)
};
return (
<View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
<Button title="Go to first screen" onPress={() => handleDismiss(3)} />
</View>
);
}
dismissAll actionTo return to the first screen in the closest stack. This is similar to popToTop stack action.
For example, the home route is the first screen, and the settings is the last. To go from settings to home route you'll have to go back to details. However, using the dismissAll action, you can go from settings to home and dismiss any screen in between.
import { Button, View, Text } from "react-native";
import { useRouter } from "expo-router";
export default function Settings() {
const router = useRouter();
const handleDismissAll = () => {
router.dismissAll()
};
return (
<View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
<Button title="Go to first screen" onPress={handleDismissAll} />
</View>
);
}
canDismiss actionTo check if it is possible to dismiss the current screen. Returns true if the router is within a stack with more than one screen in the stack's history.
import { Button, View, Text } from "react-native";
import { useRouter } from "expo-router";
export default function Settings() {
const router = useRouter();
const handleDismiss = (count) => {
if (router.canDismiss()) {
router.dismiss(count)
}
};
return (
<View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
<Button title="Maybe dismiss" onPress={() => handleDismiss()} />
</View>
);
}
The Stack navigator in Expo Router wraps the Native Stack Navigator from React Navigation. Options available in the Native Stack Navigator are all available in the Stack navigator in Expo Router.
You can also use the JavaScript-powered @react-navigation/stack library to create a custom layout component by wrapping this library with the withLayoutContext.
In the following example, JsStack component is defined using @react-navigation/stack library:
import { ParamListBase, StackNavigationState } from '@react-navigation/native';
import {
createStackNavigator,
StackNavigationEventMap,
StackNavigationOptions,
} from '@react-navigation/stack';
import { withLayoutContext } from 'expo-router';
const { Navigator } = createStackNavigator();
export const JsStack = withLayoutContext<
StackNavigationOptions,
typeof Navigator,
StackNavigationState<ParamListBase>,
StackNavigationEventMap
>(Navigator);
After defining the JsStack component, you can use it in your app:
import { JsStack } from '../layouts/js-stack';
export default function Layout() {
return (
<JsStack
screenOptions={
{
%%placeholder-start%%... %%placeholder-end%%
}
}
/>
);
}
For more information on available options, see @react-navigation/stack documentation.
For a list of all options available in the stack layout, see React Navigation's documentation.