Learn Nuxt with a Collection of 100+ Tips!

<NuxtPage>

The <NuxtPage> component is required to display pages located in the pages/ directory.

<NuxtPage> is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the pages/ directory.

<NuxtPage> is a wrapper around <RouterView> component from Vue Router.
It accepts same name and route props.
<NuxtPage> should be used instead of <RouterView> as the former takes additional care on internal states. Otherwise, useRoute() may return incorrect paths.

Props

  • name: tells RouterView to render the component with the corresponding name in the matched route record's components option.
    • type: string
  • route: route location that has all of its components resolved.
    • type: RouteLocationNormalized
  • pageKey: control when the NuxtPage component is re-rendered.
    • type: string or function
  • transition: define global transitions for all pages rendered with the NuxtPage component.
    • type: boolean or TransitionProps
  • keepalive: control state preservation of pages rendered with the NuxtPage component.
    • type: boolean or KeepAliveProps
Nuxt automatically resolves the name and route by scanning and rendering all Vue component files found in the /pages directory.

Example

For example, passing static key, NuxtPage component is rendered only once when it is mounted.

app.vue
<template>
  <NuxtPage page-key="static" />
</template>

You can also use a dynamic key based on the current route:

<NuxtPage :page-key="route => route.fullPath" />
Don't use $route object here as it can cause problems with how <NuxtPage> renders pages with <Suspense>.

Alternatively, pageKey can be passed as a key value via definePageMeta from the <script> section of your Vue component in the /pages directory.

pages/my-page.vue
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath
})
</script>
Read and edit a live example in Docs > Examples > Routing > Pages.

Page's Ref

To get the ref of a page component, access it through ref.value.pageRef

app.vue
<script setup lang="ts">
const page = ref()

function logFoo () {
  page.value.pageRef.foo()
}
</script>

<template>
  <NuxtPage ref="page" />
</template>
my-page.vue
<script setup lang="ts">
const foo = () => {
  console.log('foo method called')
}

defineExpose({
  foo,
})
</script>

Custom Props

In addition, <NuxtPage> also accepts custom props that you may need to pass further down the hierarchy.

These custom props are accessible via attrs in the Nuxt app.

<NuxtPage :foobar="123" />

For example, in the above example, the value of foobar will be available using $attrs.foobar in the template or useAttrs().foobar in <script setup>.

Read more in Docs > Guide > Directory Structure > Pages.