definePageMeta signature and return type
definePageMeta is a compiler macro with the signature: export function definePageMeta (meta: PageMeta): void. It returns void.
utils/define-page-meta
24 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
definePageMeta purpose and location
definePageMeta is a compiler macro used to set metadata for page components located in the app/pages/ directory (unless set otherwise in nuxt.config). It allows setting custom metadata for each static or dynamic route of a Nuxt application.
PageMeta interface complete specification
The PageMeta interface has the following properties: validate (function taking RouteLocationNormalized and returning boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>); redirect (RouteRecordRedirectOption); name (string); path (string); props (RouteRecordRaw['props']); alias (string | string[]); groups (string[], added in v4.3); pageTransition (boolean | TransitionProps); layoutTransition (boolean | TransitionProps); viewTransition (ViewTransitionPageOptions['enabled'] | ViewTransitionPageOptions); key (false | string | function taking RouteLocationNormalizedLoaded returning string); keepalive (boolean | KeepAliveProps); layout (false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey> | object with name and props); middleware (MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>); scrollToTop (boolean | function); [key: string] (unknown for custom metadata).
definePageMeta validate parameter
The validate property is a function that receives a RouteLocationNormalized route parameter and returns boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>. It validates whether a given route can validly be rendered with the page. Return true if valid, false if not. If another match cannot be found, a 404 will result. You can also directly return an object with status/statusText to respond immediately with an error.
definePageMeta name parameter
The name property is a string that defines a name for the page's route. By default, the name is generated based on the path inside the app/pages/ directory.
definePageMeta path parameter
The path property is a string that allows defining a custom regular expression for more complex patterns than can be expressed with file names.
definePageMeta props parameter
The props property is of type RouteRecordRaw['props'] and allows accessing route params as props passed to the page component.
definePageMeta alias parameter
The alias property is a string or string[] that defines aliases for the route record. Aliases allow defining extra paths that will behave like a copy of the record, such as having paths shorthands like /users/:id and /u/:id. All alias and path values must share the same params.
definePageMeta groups parameter
The groups property is a string[] that defines route groups the page belongs to, based on folder structure. It is automatically populated for pages within route groups. Added in v4.3.
definePageMeta keepalive parameter
The keepalive property is boolean | KeepAliveProps. Set to true to preserve page state across route changes, or use KeepAliveProps for fine-grained control.
definePageMeta key parameter
The key property is false | string | function taking RouteLocationNormalizedLoaded and returning string. Set the key value when you need more control over when the NuxtPage component is re-rendered.
definePageMeta layout parameter
The layout property is false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey> | object with optional name (LayoutKey | false) and props (Record<string, unknown>). Set a static or dynamic name of the layout for each route. Set to false to disable the default layout. Can pass an object with name and props to pass typed props to the layout component. When the layout defines props with defineProps, they will be fully typed in definePageMeta.
definePageMeta layoutTransition parameter
The layoutTransition property is boolean | TransitionProps. Set the name of the transition to apply for the current layout, or set to false to disable the layout transition.
definePageMeta middleware parameter
The middleware property is MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>. Define anonymous or named middleware directly within definePageMeta.
definePageMeta pageTransition parameter
The pageTransition property is boolean | TransitionProps. Set the name of the transition to apply for the current page, or set to false to disable the page transition.
definePageMeta viewTransition parameter
The viewTransition property is boolean | 'always' | ViewTransitionPageOptions. This is an experimental feature only available when enabled in nuxt.config. Enable/disable View Transitions for the current page. If set to true, Nuxt will not apply the transition if the user's browser matches prefers-reduced-motion: reduce (recommended). If set to 'always', Nuxt will always apply the transition. Can also pass a ViewTransitionPageOptions object with enabled (boolean | 'always'), types (string[] | function), toTypes (string[] | function), or fromTypes (string[] | function) to configure view transition types.
definePageMeta redirect parameter
The redirect property is of type RouteRecordRedirectOption and specifies 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.
definePageMeta scrollToTop parameter
The scrollToTop property is boolean | function taking (to: RouteLocationNormalized, from: RouteLocationNormalized) and returning boolean. Tell Nuxt to scroll to the top before rendering the page or not. Navigation is independent from rendering, so scroll behavior is always triggered even when the page doesn't re-render (e.g. when using a fixed key). Set scrollToTop to false to disable scrolling in such cases.
definePageMeta custom metadata support
Apart from the defined properties, you can also set custom metadata via [key: string] of type any. Custom metadata can be set in a type-safe way by augmenting the type of the meta object.
definePageMeta example with key as function and keepalive
Example code showing key as a function returning route.fullPath and keepalive with exclude property for modal component: ```vue <script setup lang="ts"> definePageMeta({ key: route => route.fullPath, keepalive: { exclude: ['modal'], }, pageType: 'Checkout', }) </script> ```
definePageMeta example with middleware function and string
Example showing middleware defined as a function, a string, or multiple strings: ```vue <script setup lang="ts"> definePageMeta({ middleware: [ function (to, from) { const auth = useState('auth') if (!auth.value.authenticated) { return navigateTo('/login') } if (to.path !== '/checkout') { return navigateTo('/checkout') } }, ], middleware: 'auth', middleware: ['auth', 'another-named-middleware'], }) </script> ```
definePageMeta example with custom path regex
Example showing custom regular expression for path to resolve conflicts between overlapping routes. For route [postId]-[postSlug].vue matching only digits for postId: ```vue <script setup lang="ts"> definePageMeta({ path: '/:postId(\\d+)-:postSlug', }) </script> ``` This ensures the route only matches when postId contains digits, distinguishing it from [categorySlug].vue routes.
definePageMeta example with layout configuration
Example showing how to set a custom layout or disable the default layout: ```vue <script setup lang="ts"> definePageMeta({ layout: 'admin', layout: false, }) </script> ```
definePageMeta example passing props to layout
Example showing how to pass typed props to a layout using object syntax for layout property: Page file (app/pages/dashboard.vue): ```vue <script setup lang="ts"> definePageMeta({ layout: { name: 'panel', props: { sidebar: true, title: 'Dashboard', }, }, }) </script> ``` Layout file (app/layouts/panel.vue): ```vue <script setup lang="ts"> const props = defineProps<{ sidebar?: boolean title?: string }>() </script> <template> <div> <aside v-if="sidebar"> Sidebar </aside> <main> <h1>{{ title }}</h1> <slot /> </main> </div> </template> ``` Layout props set via definePageMeta are fully typed based on the layout's defineProps with autocomplete and type-checking in the editor.