Nuxt/docs/3.api/1.components/2.nuxt-page.md

title	description	links
<NuxtPage>	The <NuxtPage> component is required to display pages located in the pages/ directory.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/page.ts xs

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

::note <NuxtPage> is a wrapper around <RouterView> from Vue Router. It should be used instead of <RouterView> because the former takes additional care of internal states. Otherwise, useRoute() may return incorrect paths. ::

<NuxtPage> includes the following components:

<template>
  <RouterView #default="{ Component }">
    <!-- Optional, when using transitions -->
    <Transition>
      <!-- Optional, when using keep-alive -->
      <KeepAlive>
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </KeepAlive>
    </Transition>
  </RouterView>
</template>

By default, Nuxt does not enable <Transition> and <KeepAlive>. You can enable them in the nuxt.config file or by setting the transition and keepalive properties on <NuxtPage>. If you want to define a specific page, you can set it in definePageMeta in the page component.

::warning If you enable <Transition> in your page component, ensure that the page has a single root element. ::

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

::tip Nuxt automatically resolves the name and route by scanning and rendering all Vue component files found in the /pages directory. ::

Example

For example, if you pass a key that never changes, the <NuxtPage> component will be rendered only once - when it is first mounted.

<template>
  <NuxtPage page-key="static" />
</template>

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

<NuxtPage :page-key="route => route.fullPath" />

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

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

:link-example{to="/docs/examples/routing/pages"}

Page's Ref

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

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

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

<template>
  <NuxtPage ref="page" />
</template>

<script setup lang="ts">
const foo = () => {
  console.log('foo method called')
}

defineExpose({
  foo,
})
</script>

Custom Props

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

For example, in the below example, the value of foobar will be passed to the NuxtPage component and then to the page components.

<template>
  <NuxtPage :foobar="123" />
</template>

We can access the foobar prop in the page component:

<script setup lang="ts">
const props = defineProps<{ foobar: number }>()

console.log(props.foobar) // Outputs: 123

If you have not defined the prop with defineProps, any props passed down to NuxtPage can still be accessed directly from the page attrs:

<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // Outputs: 123
</script>

:read-more{to="/docs/guide/directory-structure/pages"}