Nuxt/docs/content/2.guide/2.directory-structure/1.pages.md

icon	title	head.title
IconDirectory	pages	Pages Directory

Pages Directory

Nuxt provides a file-based routing to create routes within your web application using Vue Router under the hood.

::alert{type="info"} This directory is optional, meaning that vue-router won't be included if you only use app.vue, reducing your application's bundle size. ::

Usage

Pages are Vue components and can have the .vue, .js, .jsx, .ts or .tsx extension.

::code-group

<template>
  <h1>Index page</h1>
</template>

// https://vuejs.org/guide/extras/render-function.html
export default defineComponent({
  render () {
    return h('h1', 'Index page')
  }
})

// https://v3.nuxtjs.org/examples/advanced/jsx
// https://vuejs.org/guide/extras/render-function.html#jsx-tsx
export default defineComponent({
  render () {
    return <h1>Index page</h1>
  }
})

::

The pages/index.vue file will be mapped to the / route of your application.

If you are using app.vue, make sure to use the <NuxtPage/> component to display the current page:

<template>
  <div>
    <!-- Markup shared across all pages, ex: NavBar -->
    <NuxtPage />
  </div>
</template>

Pages must have a single root element to allow route transitions between pages. (HTML comments are considered elements as well.)

This means that when the route is server-rendered, or statically generated, you will be able to see its contents correctly, but when you navigate towards that route during client-side navigation the transition between routes will fail and you'll see that the route will not be rendered.

Here are some examples to illustrate what a page with a single root element looks like:

::code-group

<template>
  <div>
    <!-- This page correctly has only one single root element -->
    Page content
  </div>
</template>

<template>
  <!-- This page will not render when route changes during client side navigation, because of this comment -->
  <div>Page content</div>
</template>

<template>
  <div>This page</div>
  <div>Has more than one root element</div>
  <div>And will not render when route changes during client side navigation</div>
</template>

::

Dynamic Routes

If you place anything within square brackets, it will be turned into a dynamic route parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.

If you want a parameter to be optional, you must enclose it in double square brackets - for example, ~/pages/[[slug]]/index.vue or ~/pages/[[slug]].vue will match both / and /test.

Example

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

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

<template>
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>

Navigating to /users-admins/123 would render:

<p>admins - 123</p>

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.

<script setup>
const route = useRoute()

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

Catch-all Route

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.

<template>
  <p>{{ $route.params.slug }}</p>
</template>

Navigating to /hello/world would render:

<p>["hello", "world"]</p>

::alert{type="info"} Nuxt also supports a custom pages/404.vue file which will handle all routes that are not otherwise matched (and set a 404 error code). ::

Nested Routes

It is possible to display nested routes with <NuxtPage>.

Example:

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

This file tree will generate these routes:

[
  {
    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 <NuxtPage> component inside pages/parent.vue:

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>

Child Route Keys

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

<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :page-key="someKey" />
  </div>
</template>

Or alternatively:

<script setup>
definePageMeta({
  key: route => route.fullPath
})
</script>

:LinkExample{link="/examples/routing/pages"}

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

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

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

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

Much like defineEmits or defineProps (see Vue docs), 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.

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

const title = ref('')

definePageMeta({
  title,  // This will create an error
  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:

keepalive

Nuxt will automatically wrap your page in the Vue <KeepAlive> component if you set keepalive: true in your definePageMeta. This might be useful to do, for example, in a parent route that has dynamic child routes, if you want to preserve page state across route changes. You can also set props to be passed to <KeepAlive> (see a full list here).

You can set a default value for this property in your nuxt.config.

key

See above.

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.

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), or an array of strings/functions. More about named middleware.

layoutTransition and pageTransition

You can define transition properties for the <transition> component that wraps your pages and layouts, or pass false to disable the <transition> wrapper for that route. You can see a list of options that can be passed here or read more about how transitions work.

You can set default values for these properties in your nuxt.config.

alias

You can define page aliases. They allow you to access the same page from different paths. It can be either a string or an array of strings as defined here on vue-router documentation.

Typing Custom Metadata

If you add custom metadata for your pages, you may wish to do so in a type-safe way. It is possible to augment the type of the object accepted by definePageMeta:

declare module '#app' {
  interface PageMeta {
    pageType?: string
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}

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.

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

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

::alert{type="info"} Learn more about <NuxtLink> usage. ::

Router Options

It is possible to cutomize vue-router options.

Using app/router.options

This is the recommended way to specify router options.

import type { RouterOptions } from '@nuxt/schema'

// https://router.vuejs.org/api/interfaces/routeroptions.html
export default <RouterOptions> {
}

Custom Routes

:StabilityEdge{title="custom routes"}

You can optionally override routes using a function that accepts scanned routes and returns customized routes. If returning null or undefined, Nuxt will fallback to the default routes. (useful to modify input array)

import type { RouterOptions } from '@nuxt/schema'

// https://router.vuejs.org/api/interfaces/routeroptions.html
export default <RouterOptions> {
  routes: (_routes) => [
    {
      name: 'home',
      route: '/',
      component: () => import('~/pages/home.vue')
    }
  ],
}

Custom History (advanced)

:StabilityEdge{title="custom history"}

You can optionally override history mode using a function that accepts base url and returns history mode. If returning null or undefined, Nuxt will fallback to the default history.

import type { RouterOptions } from '@nuxt/schema'
import { createMemoryHistory } from 'vue-router'

// https://router.vuejs.org/api/interfaces/routeroptions.html
export default <RouterOptions> {
  history: base => process.client ? createMemoryHistory(base) : null /* default */
}

Using nuxt.config

Note: Only JSON serializable options are configurable:

• linkActiveClass
• linkExactActiveClass
• end
• sensitive
• strict
• hashMode

export default defineNuxtConfig({
  router: {
    // https://router.vuejs.org/api/interfaces/routeroptions.html
    options: {}
  }
})

Hash Mode (SPA)

:StabilityEdge{title="hash mode"}

You can enable hash history in SPA mode. In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the URL is never sent to the server and SSR is not supported.

export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true
    }
  }
})

Programmatic Navigation

Nuxt 3 allows programmatic navigation through the navigateTo() utility method. Using this utility method, you will be able to programmatically navigate the user in your app. This is great for taking input from the user and navigating them dynamically throughout your application. In this example, we have a simple method called navigate() that gets called when the user submits a search form.

Note: Ensure to always await on navigateTo or chain its result by returning from functions.

<script setup>
const router = useRouter();
const name = ref('');
const type = ref(1);

function navigate(){
  return navigateTo({
    path: '/search',
    query: {
      name: name.value,
      type: type.value
    }
  })
}
</script>