> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nuxt/nuxt/llms.txt
> Use this file to discover all available pages before exploring further.

# <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 `app/pages/` directory.

<Note>
  `<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) 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.
</Note>

## Usage

`<NuxtPage>` includes the following components:

```vue theme={null}
<template>
  <RouterView v-slot="{ 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.
</Warning>

Since `<NuxtPage>` uses `<Suspense>` under the hood, the component lifecycle behavior during page changes differs from that of a typical Vue application.

In a typical Vue application, a new page component is mounted **only after** the previous one has been fully unmounted. However, in Nuxt, due to how Vue `<Suspense>` is implemented, the new page component is mounted **before** the previous one is unmounted.

## Props

<ParamField path="name" type="string">
  Tells `<RouterView>` to render the component with the corresponding name in the matched route record's components option.
</ParamField>

<ParamField path="route" type="RouteLocationNormalized">
  Route location that has all of its components resolved.
</ParamField>

<ParamField path="pageKey" type="string | function">
  Control when the `NuxtPage` component is re-rendered.
</ParamField>

<ParamField path="transition" type="boolean | TransitionProps">
  Define global transitions for all pages rendered with the `NuxtPage` component. See [Vue's TransitionProps](https://vuejs.org/api/built-in-components#transition).
</ParamField>

<ParamField path="keepalive" type="boolean | KeepAliveProps">
  Control state preservation of pages rendered with the `NuxtPage` component. See [Vue's KeepAliveProps](https://vuejs.org/api/built-in-components#keepalive).
</ParamField>

<Tip>
  Nuxt automatically resolves the `name` and `route` by scanning and rendering all Vue component files found in the `/pages` directory.
</Tip>

## Example

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

```vue [app/app.vue] theme={null}
<template>
  <NuxtPage page-key="static" />
</template>
```

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

```html theme={null}
<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>`.
</Warning>

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

```vue [app/pages/my-page.vue] theme={null}
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
})
</script>
```

## Page's Ref

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

```vue [app/app.vue] theme={null}
<script setup lang="ts">
const page = ref()

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

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

```vue [my-page.vue] theme={null}
<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.

```vue [app/app.vue] theme={null}
<template>
  <NuxtPage :foobar="123" />
</template>
```

We can access the `foobar` prop in the page component:

```vue [app/pages/page.vue] theme={null}
<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`:

```vue [app/pages/page.vue] theme={null}
<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // Outputs: 123
</script>
```