struxadotcloud/struxa

public

initial commitd4cb9e15 months ago286 lines · 7.3 KB

1	# Parallel & Intercepting Routes
2
3	Parallel routes render multiple pages in the same layout. Intercepting routes show a different UI when navigating from within your app vs direct URL access. Together they enable modal patterns.
4
5	## File Structure
6
7	```
8	app/
9	├── @modal/ # Parallel route slot
10	│ ├── default.tsx # Required! Returns null
11	│ ├── (.)photos/ # Intercepts /photos/*
12	│ │ └── [id]/
13	│ │ └── page.tsx # Modal content
14	│ └── [...]catchall/ # Optional: catch unmatched
15	│ └── page.tsx
16	├── photos/
17	│ └── [id]/
18	│ └── page.tsx # Full page (direct access)
19	├── layout.tsx # Renders both children and @modal
20	└── page.tsx
21	```
22
23	## Step 1: Root Layout with Slot
24
25	```tsx
26	// app/layout.tsx
27	export default function RootLayout
28	children,
29	modal,
30	}: {
31	children: React
32	modal: React
33	}) {
34	return (
35	<html>
36	<body>
37	{children}
38	{modal}
39	</body>
40	</html>
41	);
42	}
43	```
44
45	## Step 2: Default File (Critical!)
46
47	**Every parallel route slot MUST have a `default.tsx
48
49	```tsx
50	// app/@modal/default.tsx
51	export default function Default
52	return null;
53	}
54	```
55
56	Without this file, refreshing any page will 404 because Next.js can't determine what to render in the `@modal` slot.
57
58	## Step 3: Intercepting Route (Modal)
59
60	The `(.)` prefix intercepts routes at the same level.
61
62	```tsx
63	// app/@modal/(.)photos/[id]/page.tsx
64	import { Modal }
65
66	export default async function
67	const { id
68	const photo =
69
70	return (
71	<Modal>
72	<img src={
73	</Modal>
74	);
75	}
76	```
77
78	## Step 4: Full Page (Direct Access)
79
80	```tsx
81	// app/photos/[id]/page.tsx
82	export default async function
83	const { id
84	const photo =
85
86	return (
87	<div className="
88	<img src={
89	<h1>{photo.
90	</div>
91	);
92	}
93	```
94
95	## Step 5: Modal Component with Correct Closing
96
97	**Critical: Use `router.back()
98
99	```tsx
100	// components/modal.tsx
101	"use client";
102
103	import { useRouter }
104	import { useCallback, useEffect
105
106	export function Modal({
107	const router =
108	const overlayRef =
109
110	// Close on escape key
111	useEffect(() =>
112	function onKeyDown(e
113	if (e.key
114	router.back();
115	}
116	}
117	document.addEventListener("keydown
118	return () =>
119	}, [router]);
120
121	// Close on overlay click
122	const handleOverlayClick =
123	(e: React
124	if (e.target
125	router.back();
126	}
127	},
128	[router],
129	);
130
131	return (
132	<div
133	ref={overlayRef}
134	onClick={handleOverlayClick}
135	className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
136	>
137	<div className="
138	<button
139	onClick={() =>
140	className="absolute top-4 right-4"
141	>
142	Close
143	</button>
144	{children}
145	</div>
146	</div>
147	);
148	}
149	```
150
151	### Why NOT `
152
153	Using `push` or `Link` to "close" a modal:
154
155	1. Adds a new history entry (back button shows modal again)
156	2. Doesn't properly clear the intercepted route
157	3. Can cause the modal to flash or persist unexpectedly
158
159	`router.back()` correctly:
160
161	1. Removes the intercepted route from history
162	2. Returns to the previous page
163	3. Properly unmounts the modal
164
165	## Route Matcher Reference
166
167	Matchers match route segments, not filesystem paths:
168
169	\| Matcher \| Matches \| Example \|
170	\| ---------- \| ------------- \|
171	\| `(.)` \| Same level \|
172	\| `(..)` \| One level up \|
173	\| `(..)(..)` \| Two levels up \| Rarely used
174	\| `(...)` \| From root \|
175
176	Common mistake: Thinking `(..)
177
178	## Handling Hard Navigation
179
180	When users directly visit `/photos/123` (bookmark, refresh, shared link):
181
182	- The intercepting route is bypassed
183	- The full `photos/[id]/page.tsx` renders
184	- Modal doesn't appear (expected behavior)
185
186	If you want the modal to appear on direct access too, you need additional logic:
187
188	```tsx
189	// app/photos/[id]/page.tsx
190	import { Modal }
191
192	export default async function
193	const { id
194	const photo =
195
196	// Option: Render as modal on direct access too
197	return (
198	<Modal>
199	<img src={
200	</Modal>
201	);
202	}
203	```
204
205	## Common Gotchas
206
207	### 1. Missing `
208
209	Every `@slot` folder needs a `default.tsx` that returns `
210
211	### 2. Modal Persists After Navigation
212
213	You're using `router.push()` instead of `router.back()`.
214
215	### 3. Nested Parallel Routes Need Defaults Too
216
217	If you have `@modal` inside a route group, each level needs its own `default.tsx`:
218
219	```
220	app/
221	├── (marketing)/
222	│ ├── @modal/
223	│ │ └── default.tsx # Needed!
224	│ └── layout.tsx
225	└── layout.tsx
226	```
227
228	### 4. Intercepted Route Shows Wrong Content
229
230	Check your matcher:
231
232	- `(.)photos` intercepts `/photos` from the same route level
233	- If your `@modal` is in `app/dashboard/@modal`, use
234
235	### 5. TypeScript Errors with `
236
237	In Next.js 15+, `params` is a Promise:
238
239	```tsx
240	// Correct
241	export default async function
242	const { id
243	}
244	```
245
246	## Complete Example: Photo Gallery Modal
247
248	```
249	app/
250	├── @modal/
251	│ ├── default.tsx
252	│ └── (.)photos/
253	│ └── [id]/
254	│ └── page.tsx
255	├── photos/
256	│ ├── page.tsx # Gallery grid
257	│ └── [id]/
258	│ └── page.tsx # Full photo page
259	├── layout.tsx
260	└── page.tsx
261	```
262
263	Links in the gallery:
264
265	```tsx
266	// app/photos/page.tsx
267	import Link from "next/link
268
269	export default async function
270	const photos =
271
272	return (
273	<div className="
274	{photos.map((
275	<Link key=
276	<img src={
277	</Link>
278	))}
279	</div>
280	);
281	}
282	```
283
284	Clicking a photo → Modal opens (intercepted)
285	Direct URL → Full page renders
286	Refresh while modal open → Full page renders