---
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 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
```

## 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 like 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 of `<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 `<NuxtChild>` 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 `<NuxtChild>` component inside `pages/parent.vue`:

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