Only provide groups for the current navigator
You can only provide groups for the current navigator. Groups in a layout only apply to routes within that navigator.
file-based-routes
129 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
Enable array syntax with initialRouteName in unstable_settings
To enable the array syntax, specify the `initialRouteName` for each group using the `unstable_settings` object in the dynamic layout. The `initialRouteName` is defined at the top level (default route for the default group) and can be nested under nested group names (e.g., `search.initialRouteName`) to set the default route for specific groups.
Array syntax (,) duplicates group children
The array syntax using parentheses and comma (,) is an advanced native app development feature that allows duplicating the children of a group. For example, `src/app/(home,search)/[user].tsx` creates both `src/app/(home)/[user].tsx` and `src/app/(search)/[user].tsx` in memory without requiring separate files for each layout.
Shared routes using groups with overlapping child routes
To match the same URL with different layouts, use groups with overlapping child routes. This pattern is common in native apps where a route like a user profile can be accessed from multiple tabs but uses only one URL. For example, a profile can be viewed in the home, search, and profile tabs, with each tab having its own layout and header, while the profile route itself is shared.
Array syntax rule: only last group segment is used for matching
When using array syntax, if there are two or more nested groups (for example, `(one)/(two)`), only the last group's segment is used for matching the route.
Navigate shared routes by including group name in URL
Shared routes can be navigated directly by including the group name in the route. For example, navigating to `/(search)/baconbrix` navigates to `/baconbrix` in the search layout.
First alphabetical group match renders on page reload
When reloading the page, the first alphabetical match is rendered among shared routes in different groups.
Example: Dynamic layout with segment prop for array syntax
```tsx src/app/(home,search)/_layout.tsx export default function DynamicLayout({ segment }) { if (segment === '(search)') { return <SearchStack />; } return <Stack />; } ``` This example shows how to use the segment prop in a layout with array syntax to render different navigation stacks for the search and home groups.
Use segment prop in layout to distinguish array syntax routes
When using array syntax to duplicate routes, use a layout's `segment` prop to distinguish between the different routes. The segment prop indicates which group the current route belongs to, allowing the layout to render different navigation stacks based on the segment value.
Example: unstable_settings configuration for array syntax
```tsx src/app/(home,search)/_layout.tsx export const unstable_settings = { initialRouteName: 'home', search: { initialRouteName: 'search', }, }; ``` In this example, 'home' is the default route for the home group and the app overall, while 'search' is the default route specifically for the search group.
Array syntax rule: first group initialRouteName used if no default provided
If there are at least two group `initialRouteNames` but a default `initialRouteName` is not provided, the first group's `initialRouteName` is used as the default.
Sharing routes between multiple tabs using route groups
Route groups can share a single screen between different tabs. Create a route group that spans multiple tab groups (e.g., (feed,search)) and place shared screens in subdirectories within that group. For example, src/app/(tabs)/(feed,search)/users/[username].tsx can be accessed from both the Feed and Search tabs at /users/evanbacon.
Shared routes deep-linking behavior with multiple groups
When deep-linking to a route shared between multiple groups (e.g., /users/evanbacon accessible from both Feed and Search tabs), Expo Router picks the first group alphabetically. When already focused on a tab and navigating to a shared route, you stay in the current tab's group.
File-based routing example project structure
Example file structure: src/app/index.tsx (initial route), src/app/home.tsx (page at /home route), src/app/_layout.tsx (root layout), src/app/profile/friends.tsx (page at /profile/friends route), src/components/app-tabs.native.tsx and src/components/app-tabs.tsx (platform-specific tab components), src/components/text-field.tsx and src/components/toolbar.tsx (non-page components). Files and directories outside src/app do not become navigation routes.
Stack and tab navigators have configuration options
Stack and tab navigators accept a wide range of configuration options for headers, animations, gestures, and more. The Stack and Tabs guides contain the full list of options and examples.
Non-navigation components live outside src/app directory
The src/app directory is exclusively for defining your app's routes. Other parts of your app, like components, hooks, utilities, and so on, should be placed in other directories such as src/components, src/hooks, and src/constants. If you put a non-route inside the src/app directory, Expo Router will attempt to treat it like a route.
Root _layout.tsx replaces App.jsx/tsx
Every project should have a _layout.tsx file directly inside the src/app directory. This file is rendered before any other route in your app and is where you would put initialization code that may have previously gone inside an App.jsx file, such as loading fonts, setting up theme providers, or interacting with the splash screen.
All screens/pages defined in src/app directory
All navigation routes in your app are defined by files and sub-directories inside the src/app directory. Every file inside src/app has a default export that defines a distinct page in your app, except for special _layout files. Directories inside src/app define groups of related screens.
Route group directories use parentheses notation
A route group is a directory where the name is surrounded in parentheses. Route groups do not count as part of the URL. You can use route groups to organize related screens that should appear in a deeper part of your navigation tree without affecting the URL structure.
First index.tsx file is the initial route
When you open your app, Expo Router looks for the first index.tsx file matching the / URL. You do not define an initial route in code. In the default template, this is src/app/index.tsx. If the app should start in a deeper part of your navigation tree, you can use a route group (directory with name surrounded in parentheses), which will not count as part of the URL.
All pages have a URL matching file location
All pages have a URL path that matches the file's location in the src/app directory. This URL can be used to navigate to that page in the address bar on the web, or as an app-specific deep link in a native mobile app. All pages in your app can be navigated to with a URL, regardless of platform.
_layout.tsx files define route relationships
_layout.tsx files are special files that are not pages themselves but define how groups of routes inside a directory relate to each other. Layout routes define relationships using a stack navigator or tab navigator component. Layout routes are rendered before the actual page routes inside their directory.
Route groups with parentheses
A directory name surrounded in parentheses indicates a route group. Route groups are useful for grouping routes together without affecting the URL. For example, src/app/(home)/settings.tsx will have /settings as its URL, even though it is not directly in the src/app directory. Route groups do not factor into the URL.
Index files as default routes
An index.tsx file indicates the default route for a directory. For example, profile/index.tsx matches /profile. A file named (home)/index.tsx matches /, effectively becoming the default route for the entire app.
Static routes - simple file and directory names
Regular file and directory names without any notation signify static routes. The URL matches exactly as the files appear in the file tree. For example, a file named favorites.tsx inside the feed directory will have a URL of /feed/favorites.
Dynamic routes with square brackets
Square brackets in a file or directory name indicate a dynamic route. The name includes a parameter that can be used when rendering the page. For example, [userName].tsx matches /evanbacon, /expo, or any other username. The parameter can be accessed with the useLocalSearchParams hook.
+middleware for request processing
+middleware is a special route used to run code before a route is rendered, allowing you to perform tasks like authentication or redirection for every request.
Plus sign routes have special significance
Routes that include a + have special significance to Expo Router and are used for specific purposes. Examples include +not-found (catches requests that don't match a route), +html (customizes HTML boilerplate on web), +native-intent (handles deep links that don't match a specific route), and +middleware (runs code before a route is rendered).
Reserved paths to avoid in routing
Some path names such as /assets are reserved by Metro and Expo Router and should be avoided for routes. A complete list of reserved paths is available in the Reserved paths documentation.
Root layout is rendered first
The _layout.tsx file directly inside the src/app directory is rendered before anything else in the app and is where you would put initialization code that may have previously gone inside an App.jsx file.
+native-intent for deep link handling
+native-intent is a special route used to handle deep links into an app that don't match a specific route, such as links generated by third-party services.
+html for web customization
+html is a special route used to customize the HTML boilerplate used by an app on web.
+not-found route for unmatched routes
+not-found is a special route that catches any requests that don't match a route in your app and will be displayed if the user navigates to a route that doesn't exist.
Slot component for layout without navigator
Use the Slot component from 'expo-router' to create a layout without a navigator. Slot serves as a placeholder for the current child route. This is helpful for adding a header or footer around routes, or displaying a modal over any route in a directory. Navigating between pages replaces the current page rather than pushing onto a stack.
Root layout with Stack and initialization example
Example of a root layout that loads fonts and shows a splash screen: import { useFonts } from 'expo-font'; import { Stack } from 'expo-router'; import * as SplashScreen from 'expo-splash-screen'; import { useEffect } from 'react'; SplashScreen.preventAutoHideAsync(); export default function RootLayout() { const [loaded] = useFonts({ SpaceMono: require('@/assets/fonts/SpaceMono-Regular.ttf'), }); useEffect(() => { if (loaded) { SplashScreen.hide(); } }, [loaded]); if (!loaded) { return null; } return <Stack />; }
Root layout in src/app/_layout.tsx
Every app should have a _layout.tsx file directly inside the src/app directory. This is the root layout and represents the entry point for navigation. It describes the top-level navigator and is where initialization code goes, such as loading fonts, interacting with the splash screen, or adding context providers. This is where you would put code that previously went inside an App.jsx file.
Slot layout with header and footer example
Example of a layout using Slot: import { Slot } from 'expo-router'; export default function Layout() { return ( <> <Header /> <Slot /> <Footer /> </> ); }
_layout.tsx defines navigation structure for directory
Each directory within src/app (including src/app itself) can define a _layout.tsx file. This file defines how all pages within that directory are arranged, such as a stack navigator, tab navigator, drawer navigator, or other layout. The layout file exports a default component that is rendered before the page you navigate to within that directory.
URL-based page references in navigation
Pages are referred to by their URL or position relative to the src/app directory. Examples: src/app/index.tsx navigated via router.navigate('/'), src/app/about.tsx via router.navigate('/about'), src/app/profile/index.tsx via router.navigate('/profile'), src/app/profile/friends.tsx via router.navigate('/profile/friends').
Dynamic routes file structure and navigation
Dynamic route segments use bracket notation in filenames, such as [id].tsx. Dynamic routes can be linked to either with their full URL (e.g., '/user/bacon') or by passing a params object with pathname and params (e.g., { pathname: '/user/[id]', params: { id: 'bacon' } }).
+not-found route for unmatched routes
Create a file named +not-found.tsx in your app directory to handle unmatched routes. You can export a custom component to render instead of the default Unmatched component. It is recommended to include a link to / so users can navigate back to the home screen.
Web route priority order
On web, files are served in the following order: 1) Static files in the public directory, 2) Standard and dynamic routes in the app directory, 3) API routes in the app directory, 4) Not-found routes served last with a 404 status code.
Path aliases configuration with src directory
When using the src directory, add path aliases to tsconfig.json to enable short import paths. Add a paths entry mapping '@/*' to './src/*' in the compilerOptions. The tsconfig.json should extend 'expo/tsconfig.base' and include the pattern mappings.
Typed routes feature in Expo Router
Typed routes can be enabled in the app config by setting experiments.typedRoutes to true in app.json.
Expo Router entry point configuration
Set the main entry point in package.json to 'expo-router/entry'. The initial client file is src/app/_layout.tsx (or app/_layout.tsx if not using the src directory).
Expo Router dependencies to install
To manually add Expo Router to an existing project, install the following dependencies using the command: npx expo install expo-router react-native-safe-area-context react-native-screens expo-linking expo-constants expo-status-bar. This command will install versions compatible with the Expo SDK version the project is using.
Expo Router vs React Navigation: file-based vs manual
Expo Router takes a file-based approach where routes are derived from file structure in the app directory, with built-in support for typed routes, automatic deep linking, and static rendering for web. React Navigation lets you define navigators and routes manually in code.
Expo Router available only in Expo CLI projects with Metro
Due to the deep connection between the router and the bundler, Expo Router is only available in Expo CLI projects with Metro. However, you can use Expo CLI in any React Native project.
File-based routing enables easier refactoring
With file-based routing in Expo Router, refactoring is easier because you can move files around without having to update any imports or routing components.
Expo Router key feature: Static rendering on web and universal linking
Expo Router enables build-time static rendering on web and universal linking to native, allowing app content to be indexed by search engines.
Expo Router key feature: Universal Fast Refresh across platforms
Expo Router provides universal Fast Refresh across Android, iOS, and web, along with artifact memoization in the bundler to keep iteration fast at scale.
Expo Router key feature: Automatic lazy-evaluation and route optimization
Routes are automatically optimized with lazy-evaluation in production and deferred bundling in development.
Expo Router key feature: Offline-first with caching
Expo Router apps are cached and run offline-first, with automatic updates when you publish a new version. Apps handle all incoming native URLs without a network connection or server.
Expo Router key feature: Shareable with automatic deep linking
Every screen in an Expo Router app is automatically deep linkable, making any route in the app shareable with links.
Expo Router key feature: Native built on React Native Screens
Expo Router navigation is built on top of React Native Screens and is truly native and platform-optimized by default.
Quick start command for creating new Expo app with Router
To create a new Expo app with Expo Router already installed and configured, use create-expo-app with the template flag. For SDK 57 projects, run: npx create-expo-app@latest --template default@sdk-57
Expo Router brings file-system routing concepts from web to universal applications
Expo Router brings the best file-system routing concepts from the web to a universal application, allowing routing to work across every platform. This brings web-like routing patterns to React Native applications.
Expo Router comparison to web frameworks
Expo Router is an opinionated framework for React Native, similar to how Remix and Next.js are opinionated frameworks for web-only React. It brings the best architectural patterns to React Native development.
Expo Router is a file-based router for React Native and web
Expo Router is a file-based router for React Native and web applications. It allows you to manage navigation between screens in your app, enabling users to move seamlessly between different parts of the app's UI using the same components on multiple platforms (Android, iOS, and web). When a file is added to the app directory, the file automatically becomes a route in your navigation.
Migration prerequisites: refactor and structure recommendations
Before migrating from React Navigation, make these recommended modifications: Split React Navigation screen components into individual files. Convert the project to TypeScript. Convert relative imports to typed aliases (e.g., ../../components/button.tsx to @/components/button). Migrate away from resetRoot. Rename the initial route to index since Expo Router considers the route opened on launch to match /, whereas React Navigation typically uses something like Home.