1---
2name: routing
3description: File-based routing, dynamic routes, navigation, and middleware in Nuxt
4---
5 
6# Routing
7 
8Nuxt uses file-system routing based on vue-router. Files in `app/pages/` automatically create routes.
9 
10## Basic Routing
11 
12```
13pages/
14├── index.vue      → /
15├── about.vue      → /about
16└── posts/
17    ├── index.vue  → /posts
18    └── [id].vue   → /posts/:id
19```
20 
21## Dynamic Routes
22 
23Use brackets for dynamic segments:
24 
25```
26pages/
27├── users/
28│   └── [id].vue       → /users/:id
29├── posts/
30│   └── [...slug].vue  → /posts/* (catch-all)
31└── [[optional]].vue   → /:optional? (optional param)
32```
33 
34Access route parameters:
35 
36```vue
37<script setup lang="ts">
38const route = useRoute()
39// /posts/123 → route.params.id = '123'
40console.log(route.params.id)
41</script>
42```
43 
44## Navigation
45 
46### NuxtLink Component
47 
48```vue
49<template>
50  <nav>
51    <NuxtLink to="/">Home</NuxtLink>
52    <NuxtLink to="/about">About</NuxtLink>
53    <NuxtLink :to="{ name: 'posts-id', params: { id: 1 } }">Post 1</NuxtLink>
54  </nav>
55</template>
56```
57 
58NuxtLink automatically prefetches linked pages when they enter the viewport.
59 
60### Programmatic Navigation
61 
62```vue
63<script setup lang="ts">
64const router = useRouter()
65 
66function goToPost(id: number) {
67  navigateTo(`/posts/${id}`)
68  // or
69  router.push({ name: 'posts-id', params: { id } })
70}
71</script>
72```
73 
74## Route Middleware
75 
76### Named Middleware
77 
78```ts
79// middleware/auth.ts
80export default defineNuxtRouteMiddleware((to, from) => {
81  const isAuthenticated = false // Your auth logic
82 
83  if (!isAuthenticated) {
84    return navigateTo('/login')
85  }
86})
87```
88 
89Apply to pages:
90 
91```vue
92<script setup lang="ts">
93definePageMeta({
94  middleware: 'auth',
95  // or multiple: middleware: ['auth', 'admin']
96})
97</script>
98```
99 
100### Global Middleware
101 
102Name files with `.global` suffix:
103 
104```ts
105// middleware/logging.global.ts
106export default defineNuxtRouteMiddleware((to, from) => {
107  console.log('Navigating to:', to.path)
108})
109```
110 
111### Inline Middleware
112 
113```vue
114<script setup lang="ts">
115definePageMeta({
116  middleware: [
117    function (to, from) {
118      // Inline middleware logic
119    },
120  ],
121})
122</script>
123```
124 
125## Page Meta
126 
127Configure page-level options:
128 
129```vue
130<script setup lang="ts">
131definePageMeta({
132  title: 'My Page',
133  layout: 'custom',
134  middleware: 'auth',
135  validate: (route) => {
136    // Return false for 404, or object with status/statusText
137    return /^\d+$/.test(route.params.id as string)
138  },
139})
140</script>
141```
142 
143## Route Validation
144 
145```vue
146<script setup lang="ts">
147definePageMeta({
148  validate: (route) => {
149    // Must return boolean or object with status
150    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
151  },
152})
153</script>
154```
155 
156## Layouts
157 
158Define layouts in `app/layouts/`:
159 
160```vue
161<!-- layouts/default.vue -->
162<template>
163  <div>
164    <header>Header</header>
165    <slot />
166    <footer>Footer</footer>
167  </div>
168</template>
169```
170 
171```vue
172<!-- layouts/admin.vue -->
173<template>
174  <div class="admin">
175    <AdminSidebar />
176    <main>
177      <slot />
178    </main>
179  </div>
180</template>
181```
182 
183Use in pages:
184 
185```vue
186<script setup lang="ts">
187definePageMeta({
188  layout: 'admin',
189})
190</script>
191```
192 
193Dynamic layout:
194 
195```vue
196<script setup lang="ts">
197const layout = ref('default')
198 
199function enableAdmin() {
200  setPageLayout('admin')
201}
202</script>
203```
204 
205### Passing Props to Layouts (Nuxt 4.4+)
206 
207Use the object syntax for `layout` to pass typed props to the layout component:
208 
209```vue
210<!-- app/pages/dashboard.vue -->
211<script setup lang="ts">
212definePageMeta({
213  layout: { name: 'panel', props: { sidebar: true, title: 'Dashboard' } },
214})
215</script>
216```
217 
218```vue
219<!-- app/layouts/panel.vue -->
220<script setup lang="ts">
221const props = defineProps<{ sidebar?: boolean, title?: string }>()
222</script>
223```
224 
225Props are fully typed from the layout's `defineProps`. Also works dynamically: `setPageLayout('panel', { sidebar: true })`.
226 
227## Named Views
228 
229A route can render into multiple `<NuxtPage>` outlets. Add named view files with the `[email protected]` convention next to the default route file:
230 
231```
232pages/
233├── parent.vue
234└── parent/
235    ├── child.vue           → default <NuxtPage />
236    └── [email protected]   → <NuxtPage name="sidebar" />
237```
238 
239```vue
240<!-- pages/parent.vue -->
241<template>
242  <NuxtPage />
243  <aside><NuxtPage name="sidebar" /></aside>
244</template>
245```
246 
247`definePageMeta` is read from the default route file only.
248 
249## Navigation Hooks
250 
251```vue
252<script setup lang="ts">
253onBeforeRouteLeave((to, from) => {
254  // Confirm before leaving
255  const answer = window.confirm('Leave?')
256  if (!answer) return false
257})
258 
259onBeforeRouteUpdate((to, from) => {
260  // Called when route changes but component is reused
261})
262</script>
263```
264 
265<!-- 
266Source references:
267- https://nuxt.com/docs/4.x/getting-started/routing
268- https://nuxt.com/docs/4.x/directory-structure/app/pages
269- https://nuxt.com/docs/4.x/directory-structure/app/middleware
270- https://nuxt.com/docs/4.x/api/utils/define-page-meta
271-->
272