Nuxt/docs/3.api/3.utils/define-page-meta.md

8.1 KiB

title description links
definePageMeta Define metadata for your page components.
label icon to size
Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/pages/runtime/composables.ts xs

definePageMeta is a compiler macro that you can use to set metadata for your page components located in the pages/ directory (unless set otherwise). This way you can set custom metadata for each static or dynamic route of your Nuxt application.

<script setup lang="ts">
definePageMeta({
  layout: 'default'
})
</script>

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

Type

definePageMeta(meta: PageMeta) => void

interface PageMeta {
  validate?: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>
  redirect?: RouteRecordRedirectOption
  name?: string
  path?: string
  alias?: string | string[]
  pageTransition?: boolean | TransitionProps
  layoutTransition?: boolean | TransitionProps
  viewTransition?: boolean | 'always'
  key?: false | string | ((route: RouteLocationNormalizedLoaded) => string)
  keepalive?: boolean | KeepAliveProps
  layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
  [key: string]: unknown
}

Parameters

meta

  • Type: PageMeta

    An object accepting the following page metadata:

    name

    • Type: string

      You may define a name for this page's route. By default, name is generated based on path inside the pages/ directory.

    path

    • Type: string

      You may define a custom regular expression if you have a more complex pattern than can be expressed with the file name.

    alias

    • Type: string | string[]

      Aliases for the record. Allows defining extra paths that will behave like a copy of the record. Allows having paths shorthands like /users/:id and /u/:id. All alias and path values must share the same params.

    keepalive

    • Type: boolean | KeepAliveProps

      Set to true when you want to preserve page state across route changes or use the KeepAliveProps for a fine-grained control.

    key

    • Type: false | string | ((route: RouteLocationNormalizedLoaded) => string)

      Set key value when you need more control over when the <NuxtPage> component is re-rendered.

    layout

    • Type: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>

      Set a static or dynamic name of the layout for each route. This can be set to false in case the default layout needs to be disabled.

    layoutTransition

    • Type: boolean | TransitionProps

      Set name of the transition to apply for current layout. You can also set this value to false to disable the layout transition.

    middleware

    • Type: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>

      Define anonymous or named middleware directly within definePageMeta. Learn more about route middleware.

    pageTransition

    • Type: boolean | TransitionProps

      Set name of the transition to apply for current page. You can also set this value to false to disable the page transition.

    viewTransition

    • Type: boolean | 'always'

      Experimental feature, only available when enabled in your nuxt.config file
      Enable/disable View Transitions for the current page. If set to true, Nuxt will not apply the transition if the users browser matches prefers-reduced-motion: reduce (recommended). If set to always, Nuxt will always apply the transition.

    redirect

    • Type: RouteRecordRedirectOption

      Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location.

    validate

    • Type: (route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>

      Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with statusCode/statusMessage to respond immediately with an error (other matches will not be checked).

    scrollToTop

    • Type: boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean

      Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in ~/app/router.options.ts (see custom routing) for more info.

    [key: string]

Examples

Basic Usage

The example below demonstrates:

  • how key can be a function that returns a value;
  • how keepalive property makes sure that the <modal> component is not cached when switching between multiple components;
  • adding pageType as a custom property:
<script setup lang="ts">
definePageMeta({
  key: (route) => route.fullPath,

  keepalive: {
    exclude: ['modal']
  },

  pageType: 'Checkout'
})
</script>

Defining Middleware

The example below shows how the middleware can be defined using a function directly within the definePageMeta or set as a string that matches the middleware file name located in the middleware/ directory:

<script setup lang="ts">
definePageMeta({
  // define middleware as a function
  middleware: [
    function (to, from) {
      const auth = useState('auth')

      if (!auth.value.authenticated) {
          return navigateTo('/login')
      }

      if (to.path !== '/checkout') {
        return navigateTo('/checkout')
      }
    }
  ],

  // ... or a string
  middleware: 'auth'

  // ... or multiple strings
  middleware: ['auth', 'another-named-middleware']
})
</script>

Using a Custom Regular Expression

A custom regular expression is a good way to resolve conflicts between overlapping routes, for instance:

The two routes "/test-category" and "/1234-post" match both [postId]-[postSlug].vue and [categorySlug].vue page routes.

To make sure that we are only matching digits (\d+) for postId in the [postId]-[postSlug] route, we can add the following to the [postId]-[postSlug].vue page template:

<script setup lang="ts">
definePageMeta({
  path: '/:postId(\\d+)-:postSlug' 
})
</script>

For more examples see Vue Router's Matching Syntax.

Defining Layout

You can define the layout that matches the layout's file name located (by default) in the layouts/ directory. You can also disable the layout by setting the layout to false:

<script setup lang="ts">
definePageMeta({
  // set custom layout
  layout: 'admin'

  // ... or disable a default layout
  layout: false
})
</script>