1# Route Structure
2 
3## File Conventions
4 
5- Routes belong in the `app` directory
6- Use `[]` for dynamic routes, e.g. `[id].tsx`
7- Routes can never be named `(foo).tsx` - use `(foo)/index.tsx` instead
8- Use `(group)` routes to simplify the public URL structure
9- NEVER co-locate components, types, or utilities in the app directory - these should be in separate directories like `components/`, `utils/`, etc.
10- The app directory should only contain route and `_layout` files; every file should export a default component
11- Ensure the app always has a route that matches "/" so the app is never blank
12- ALWAYS use `_layout.tsx` files to define stacks
13 
14## Dynamic Routes
15 
16Use square brackets for dynamic segments:
17 
18```
19app/
20  users/
21    [id].tsx        # Matches /users/123, /users/abc
22    [id]/
23      posts.tsx     # Matches /users/123/posts
24```
25 
26### Catch-All Routes
27 
28Use `[...slug]` for catch-all routes:
29 
30```
31app/
32  docs/
33    [...slug].tsx   # Matches /docs/a, /docs/a/b, /docs/a/b/c
34```
35 
36## Query Parameters
37 
38Access query parameters with the `useLocalSearchParams` hook:
39 
40```tsx
41import { useLocalSearchParams } from "expo-router";
42 
43function Page() {
44  const { id } = useLocalSearchParams<{ id: string }>();
45}
46```
47 
48For dynamic routes, the parameter name matches the file name:
49 
50- `[id].tsx` → `useLocalSearchParams<{ id: string }>()`
51- `[slug].tsx` → `useLocalSearchParams<{ slug: string }>()`
52 
53## Pathname
54 
55Access the current pathname with the `usePathname` hook:
56 
57```tsx
58import { usePathname } from "expo-router";
59 
60function Component() {
61  const pathname = usePathname(); // e.g. "/users/123"
62}
63```
64 
65## Group Routes
66 
67Use parentheses for groups that don't affect the URL:
68 
69```
70app/
71  (auth)/
72    login.tsx       # URL: /login
73    register.tsx    # URL: /register
74  (main)/
75    index.tsx       # URL: /
76    settings.tsx    # URL: /settings
77```
78 
79Groups are useful for:
80 
81- Organizing related routes
82- Applying different layouts to route groups
83- Keeping URLs clean
84 
85## Stacks and Tabs Structure
86 
87When an app has tabs, the header and title should be set in a Stack that is nested INSIDE each tab. This allows tabs to have their own headers and distinct histories. The root layout should often not have a header.
88 
89- Set the 'headerShown' option to false on the tab layout
90- Use (group) routes to simplify the public URL structure
91- You may need to delete or refactor existing routes to fit this structure
92 
93Example structure:
94 
95```
96app/
97  _layout.tsx — <Tabs />
98  (home)/
99    _layout.tsx — <Stack />
100    index.tsx — <ScrollView />
101  (settings)/
102    _layout.tsx — <Stack />
103    index.tsx — <ScrollView />
104  (home,settings)/
105    info.tsx — <ScrollView /> (shared across tabs)
106```
107 
108## Array Routes for Multiple Stacks
109 
110Use array routes '(index,settings)' to create multiple stacks. This is useful for tabs that need to share screens across stacks.
111 
112```
113app/
114  _layout.tsx — <Tabs />
115  (index,settings)/
116    _layout.tsx — <Stack />
117    index.tsx — <ScrollView />
118    settings.tsx — <ScrollView />
119```
120 
121This requires a specialized layout with explicit anchor routes:
122 
123```tsx
124// app/(index,settings)/_layout.tsx
125import { useMemo } from "react";
126import Stack from "expo-router/stack";
127 
128export const unstable_settings = {
129  index: { anchor: "index" },
130  settings: { anchor: "settings" },
131};
132 
133export default function Layout({ segment }: { segment: string }) {
134  const screen = segment.match(/\((.*)\)/)?.[1]!;
135 
136  const options = useMemo(() => {
137    switch (screen) {
138      case "index":
139        return { headerRight: () => <></> };
140      default:
141        return {};
142    }
143  }, [screen]);
144 
145  return (
146    <Stack>
147      <Stack.Screen name={screen} options={options} />
148    </Stack>
149  );
150}
151```
152 
153## Complete App Structure Example
154 
155```
156app/
157  _layout.tsx — <NativeTabs />
158  (index,search)/
159    _layout.tsx — <Stack />
160    index.tsx — Main list
161    search.tsx — Search view
162    i/[id].tsx — Detail page
163components/
164  theme.tsx
165  list.tsx
166utils/
167  storage.ts
168  use-search.ts
169```
170 
171## Layout Files
172 
173Every directory can have a `_layout.tsx` file that wraps all routes in that directory:
174 
175```tsx
176// app/_layout.tsx
177import { Stack } from "expo-router/stack";
178 
179export default function RootLayout() {
180  return <Stack />;
181}
182```
183 
184```tsx
185// app/(tabs)/_layout.tsx
186import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
187 
188export default function TabLayout() {
189  return (
190    <NativeTabs>
191      <NativeTabs.Trigger name="index">
192        <Label>Home</Label>
193        <Icon sf="house.fill" />
194      </NativeTabs.Trigger>
195    </NativeTabs>
196  );
197}
198```
199 
200## Route Settings
201 
202Export `unstable_settings` to configure route behavior:
203 
204```tsx
205export const unstable_settings = {
206  anchor: "index",
207};
208```
209 
210- `initialRouteName` was renamed to `anchor` in v4
211 
212## Not Found Routes
213 
214Create a `+not-found.tsx` file to handle unmatched routes:
215 
216```tsx
217// app/+not-found.tsx
218import { Link } from "expo-router";
219import { View, Text } from "react-native";
220 
221export default function NotFound() {
222  return (
223    <View>
224      <Text>Page not found</Text>
225      <Link href="/">Go home</Link>
226    </View>
227  );
228}
229```
230