Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 71 ยท Navigation

File-Based Routing with Expo Router

Learn Expo Router: the app directory, layouts, dynamic routes, route groups, Link and router APIs and typed routes, with a runnable path matcher stand-in.

With React Navigation you write a list of screens in code. Expo Router flips that around: your file system is the route table. A file at app/about.tsx is the screen at /about. A folder with a [id].tsx file is a dynamic route. A _layout.tsx file wraps the screens next to it in a stack or tabs. If you have used Next.js, the idea will feel familiar, and the URL for every screen comes for free, which makes deep links and web support almost automatic.

Expo Router is built on top of React Navigation, so everything you learned about stacks, tabs and options still applies. You only change how the navigators are declared. This lesson explains the file conventions, the navigation APIs and typed routes.

What runs on this site. Expo Router needs a native or web build, so the real code and the folder trees are read-only. The runnable examples are stand-ins: a function that turns file names into route patterns, and a matcher that picks the winning file for a URL using the same ordering rules (static before dynamic before catch-all). The real router has many more features.

The app directory

Expo Router looks inside the app folder (or src/app). The file name decides the URL:

TEXT
app/
  _layout.tsx            wraps everything (root layout)
  (tabs)/
    _layout.tsx          tab bar for the group
    index.tsx            /
    explore.tsx          /explore
  products/
    index.tsx            /products
    [id].tsx             /products/42
  settings.tsx           /settings
  [...missing].tsx       any other path (catch-all)
  +not-found.tsx         shown when nothing matches

The rules fit on one hand:

  • index.tsx is the default screen of its folder (/ or /products).
  • A named file is a segment: settings.tsx is /settings.
  • [id].tsx is a dynamic segment: any single value matches, and the value is available as a param.
  • [...rest].tsx is a catch-all: it matches the rest of the path (one or more segments).
  • A folder in parentheses, like (tabs), is a group: it organizes files and shares a layout, but it adds nothing to the URL.
  • Files starting with _ (such as _layout.tsx) are not screens, and +not-found.tsx is a special screen for unknown URLs.

Every screen file default-exports a component:

TSX
// app/products/[id].tsx
import { useLocalSearchParams } from 'expo-router';
import { Text } from 'react-native';

export default function ProductScreen() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return <Text>Product {id}</Text>;
}

Params from the URL are always strings (or string arrays). Convert them yourself: Number(id).

File names are routes

about.tsx The route /about.
[id].tsx Any one segment.
[...rest].tsx Everything that is left.
(tabs) A group, not in the URL.
1 / 2

Layouts

A _layout.tsx file renders the navigator for the folder it sits in. Its children are the screens beside it. The root layout usually returns a stack:

TSX
// app/_layout.tsx
import { Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerStyle: { backgroundColor: '#1e293b' }, headerTintColor: '#fff' }}>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="products/[id]" options={{ title: 'Product' }} />
    </Stack>
  );
}

A group's layout can return tabs instead:

TSX
// app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';

export default function TabLayout() {
  return (
    <Tabs screenOptions={{ tabBarActiveTintColor: '#2563eb' }}>
      <Tabs.Screen name="index" options={{ title: 'Home' }} />
      <Tabs.Screen name="explore" options={{ title: 'Explore' }} />
    </Tabs>
  );
}

Stack, Tabs and Drawer are thin wrappers around the React Navigation navigators from the previous lessons, and options accepts the same keys. The name is the file name relative to the layout, without the extension. Layouts nest: a screen at app/(tabs)/explore.tsx is rendered inside the tab layout, which is rendered inside the root layout. That is exactly the "stacks and tabs inside each other" structure from Tab and Drawer Navigators, expressed as folders.

You can navigate in two ways: declaratively with Link, or imperatively with router.

TSX
import { Link, router } from 'expo-router';

// Declarative
<Link href="/settings">Settings</Link>
<Link href={{ pathname: '/products/[id]', params: { id: '42' } }}>Product 42</Link>
<Link href="/products/42" asChild>
  <Pressable><Text>Open product</Text></Pressable>
</Link>

// Imperative
router.push('/products/42');          // add a screen
router.replace('/login');             // swap the current screen
router.back();                        // go back
router.navigate('/explore');          // go to a screen, reusing an existing one if possible
router.setParams({ sort: 'price' });  // update params of the focused route

asChild passes the link behavior to your own component, such as a Pressable, instead of rendering a text link. For search params use a query string or params: router.push({ pathname: '/search', params: { q: 'lamp' } }) makes the URL /search?q=lamp. Two hooks read what the router knows:

  • useLocalSearchParams(): params of the screen where the hook is called. It updates only for that screen, which is what you almost always want.
  • useGlobalSearchParams(): params of the whole URL, even if your screen is not focused. Use it sparingly, since it re-renders on every navigation.

<Redirect href="/login" /> sends the user elsewhere when rendered, and it is the building block for protected screens, covered in Deep Linking and Authentication Flows.

Typed routes

Typos in href strings are as easy to make as typos in route names. Expo Router can generate types from your files so wrong paths fail at compile time. Enable it in app.json:

JSON
{
  "expo": {
    "experiments": { "typedRoutes": true }
  }
}

When the dev server runs, it writes a .expo/types/router.d.ts file that lists every route. After that, href="/setings" is a TypeScript error, and a dynamic route needs the right params: href={{ pathname: '/products/[id]', params: { id: '42' } }}. The generated file should stay out of git (it lives in a folder that Expo already ignores).

A path matcher stand-in

The next TryIt rebuilds the idea behind the router: it converts a list of file paths into route patterns, then matches a URL against them. It shows why (tabs) disappears from URLs, why index means the folder itself, and why /products/new beats /products/[id] when both files exist.

From files to routes (stand-in)

Try /products/new: both new.tsx and [id].tsx match, and the static file wins. Try /nothing/here: no file matches, so the real router would show +not-found.tsx. Note that /docs alone does not match the catch-all file, because a catch-all needs at least one segment.

Layouts are another thing the file system decides: every _layout.tsx along the path of a screen wraps it. The second stand-in lists them.

Which layouts wrap this screen? (stand-in)

Expo Router or React Navigation?

Both are valid. Expo Router gives you automatic deep links, typed hrefs, a web version of your app and less boilerplate, and it is the default in new Expo projects. React Navigation gives you full control in code and fits apps whose screen list is dynamic or that live in a bare React Native project without Expo. Because Expo Router is built on React Navigation, you can mix them: custom navigators and options carry over. The folder layout of a new project is covered in Project Structure and App Config.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file creates the route /products/42 for any id?

    Square brackets mark a dynamic segment. Parentheses make a group that is not part of the URL, and a leading underscore means the file is not a route.
  2. 2. What does a folder named (tabs) do to the URL?

    Groups organize files and can have their own _layout.tsx, but their name is omitted from the URL.
  3. 3. Both app/products/new.tsx and app/products/[id].tsx exist. Which one does /products/new open?

    More specific routes win: static segments beat dynamic ones, which beat catch-alls.
  4. 4. What type does useLocalSearchParams give for a dynamic id param?

    URL params are text. Parse them yourself, for example Number(id).

Summary

  • Expo Router turns the app folder into routes: index, named files, [id] dynamic segments, [...rest] catch-alls and (group) folders that do not appear in the URL.
  • _layout.tsx files return a Stack, Tabs or Drawer and nest like folders; +not-found.tsx handles unknown URLs.
  • Navigate with <Link href> or router.push, replace, back, navigate and setParams; read params with useLocalSearchParams.
  • Turn on experiments.typedRoutes to get compile-time checked hrefs.
  • It is built on React Navigation, so options and concepts carry over.
  • On this site the real code is read-only and the TryIts are matcher stand-ins.

Next, open screens from outside the app in Deep Linking and Authentication Flows.