---
icon: IconDirectory
title: 'pages'
head.title: Pages directory
---

# Pages directory

::alert{type="info"}
The `pages/` directory is optional, meaning that if you only use [app.vue](/docs/directory-structure/app), `vue-router` won't be included, reducing your application's bundle size.
::

Nuxt will automatically integrate [Vue Router](https://next.router.vuejs.org/) and map `pages/` directory into the routes of your application.

::alert{type=warning}
Unlike components, your pages must have a single root element to allow Nuxt to apply route transitions between pages.
::

## Dynamic Routes

If you place anything within square brackets, it will be turned into a [dynamic route](https://next.router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.

If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match _all_ routes under that path, and thus it doesn't support any non-dynamic text.

### Example

```bash
-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue
```

Given the example above, you can access group/id within your component via the `$route` object:

```vue
<template>
  {{ $route.params.group }}
  {{ $route.params.id }}
</template>
```

Navigating to `/users-admins/123` would render:

```text
admins 123
```

If you want to access the route using Composition API, there is a global `useRoute` function that will allow you to access the route just like `this.$route` in the Options API.

```js
<script setup>
// This import statement is optional since it's automatically imported by Nuxt.
// import { useRoute } from '#imports'

const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('Warning! Make sure user is authenticated!')
}
</script>
```

## Navigation

To navigate between pages of your app, you should use the  `<NuxtLink>` component. This component is included with Nuxt and therefore you don't have to import it as you do with other components. It is similar to the HTML `<a>` tag except that instead of using a `href="/about"` you use `to="/about"`. If you've used `vue-router` before, you can think of `<NuxtLink>` as a replacement for `<RouterLink>`.

A simple link to the `index.vue` page in your `pages` folder:

```html
<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>
```

The `<NuxtLink>` component should be used for all internal links. That means for all links to the pages within your site you should use `<NuxtLink>`. The `<a>` tag should be used for all external links. That means if you have links to other websites you should use the `<a>` tag for those.

```html
<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">
      About (internal link that belongs to the Nuxt App)
    </NuxtLink>
    <a href="https://nuxtjs.org">External Link to another page</a>
  </div>
</template>
```

::alert{type="info"}
If you want to know more about `<RouterLink>`, read the [Vue Router documentation](https://next.router.vuejs.org/api/#router-link) for more information.
::

## Nested Routes

We provide a semantic alias for `RouterView`, the `<NuxtNestedPage>` component, for displaying the children components of a [nested route](https://next.router.vuejs.org/guide/essentials/nested-routes.html).

Example:

```bash
-| pages/
---| parent/
------| child.vue
---| parent.vue
```

This file tree will generate these routes:

```js
[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child'
      }
    ]
  }
]
```

To display the `child.vue` component, you have to insert the `<NuxtNestedPage>` component inside `pages/parent.vue`:

```html{}[pages/parent.vue]
<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtNestedPage :foobar="123" />
  </div>
</template>
```

### Child route keys

If you want more control over when the `<NuxtNestedPage>` component is re-rendered (for example, for transitions), you can either pass a string or function via the `childKey` prop, or you can define a `key` value via `definePageMeta`:

```html{}[pages/parent.vue]
<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtNestedPage :child-key="someKey" />
  </div>
</template>
```

Or alternatively:

```html{}[pages/child.vue]
<script setup>
definePageMeta({
  key: route => route.fullPath
})
</script>
```

## Page Metadata

You might want to define metadata for each route in your app. You can do this using the `definePageMeta` macro, which will work both in `<script>` and in `<script setup>`:

```vue
<script setup>
definePageMeta({
  title: 'My home page'
})
```

This data can then be accessed throughout the rest of your app from the `route.meta` object.

```vue
<script setup>
const route = useRoute()
console.log(route.meta.title) // My home page
</script>
```

If you are using nested routes, the page metadata from all these routes will be merged into a single object. For more on route meta, see the [vue-router docs](https://next.router.vuejs.org/guide/advanced/meta.html#route-meta-fields).

Much like `defineEmits` or `defineProps` (see [Vue docs](https://v3.vuejs.org/api/sfc-script-setup.html#defineprops-and-defineemits)), `definePageMeta` is a **compiler macro**. It will be compiled away so you cannot reference it within your component. Instead, the metadata passed to it will be hoisted out of the component. Therefore, the page meta object cannot reference the component (or values defined on the component). However, it can reference imported bindings.

```vue
<script setup>
import { someData } from '~/utils/example'

const title = ref('')

definePageMeta({
  title,
  someData
})
</script>
```

### Special Metadata

Of course, you are welcome to define metadata for your own use throughout your app. But some metadata defined with `definePageMeta` has a particular purpose:

#### `key`

[See above](#child-route-keys).

#### `layout`

You can define the layout used to render the route. This can be either false (to disable any layout), a string or a ref/computed, if you want to make it reactive in some way. [More about layouts](/docs/directory-structure/layouts).

#### `middleware`

You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)), or an array of strings/functions. [More about named middleware](/docs/directory-structure/middleware).

#### `layoutTransition` and `pageTransition`

You can define transition properties for the `<transition>` components that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. [More about transitions](https://v3.vuejs.org/guide/transitions-overview.html).