@nuxt/docs 4.3.0 → 4.4.2

package/3.guide/2.best-practices/hydration.md

@@ -1,37 +1,37 @@
 ---
-navigation.title: 'Nuxt and hydration'
-title: Nuxt and hydration
+navigation.title: 'Nuxt and Hydration'
+title: Nuxt and Hydration
 description: Why fixing hydration issues is important
 ---
 
 When developing, you may face hydration issues. Don't ignore those warnings.
 
-# Why is it important to fix them?
+## Why is it important to fix them?
 
 Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:
 
-## Performance Impact
+### Performance Impact
 
 - **Increased time to interactive**: Hydration errors force Vue to re-render the entire component tree, which will increase the time for your Nuxt app to become interactive
 - **Poor user experience**: Users may see content flashing or unexpected layout shifts
 
-## Functionality Issues
+### Functionality Issues
 
 - **Broken interactivity**: Event listeners may not attach properly, leaving buttons and forms non-functional
 - **State inconsistencies**: Application state can become out of sync between what the user sees and what the application thinks is rendered
 - **SEO problems**: Search engines may index different content than what users actually see
 
-# How to detect them
+## How to detect them
 
-## Development Console Warnings
+### Development Console Warnings
 
 Vue will log hydration mismatch warnings in the browser console during development:
 
 ![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)
 
-# Common reasons
+## Common reasons
 
-## Browser-only APIs in Server Context
+### Browser-only APIs in Server Context
 
 **Problem**: Using browser-specific APIs during server-side rendering.
 
@@ -60,7 +60,7 @@ const userTheme = useCookie('theme', { default: () => 'light' })
 </script>
 ```
 
-## Inconsistent Data
+### Inconsistent Data
 
 **Problem**: Different data between server and client.
 
@@ -82,7 +82,7 @@ const state = useState('random', () => Math.random())
 </script>
 ```
 
-## Conditional Rendering Based on Client State
+### Conditional Rendering Based on Client State
 
 **Problem**: Using client-only conditions during SSR.
 
@@ -105,7 +105,7 @@ const state = useState('random', () => Math.random())
 </template>
 ```
 
-## Third-party Libraries with Side Effects
+### Third-party Libraries with Side Effects
 
 **Problem**: Libraries that modify the DOM or have browser dependencies (this happens a LOT with tag managers).
 
@@ -129,7 +129,7 @@ onMounted(async () => {
 </script>
 ```
 
-## Dynamic Content Based on Time
+### Dynamic Content Based on Time
 
 **Problem**: Content that changes based on current time.
 

package/3.guide/2.best-practices/performance.md

@@ -142,9 +142,8 @@ Images in your website can usually be separated by importance; the ones that are
   <NuxtImg
     src="/hero-banner.jpg"
     format="webp"
-    preload
+    :preload="{ fetchPriority: 'high' }"
     loading="eager"
-    fetch-priority="high"
     width="200"
     height="100"
   />
@@ -154,7 +153,7 @@ Images in your website can usually be separated by importance; the ones that are
     src="/facebook-logo.jpg"
     format="webp"
     loading="lazy"
-    fetch-priority="low"
+    fetchpriority="low"
     width="200"
     height="100"
   />

package/3.guide/3.ai/1.mcp.md

@@ -79,7 +79,7 @@ The Nuxt connector will appear in the composer's "Developer mode" tool later dur
 ### Claude Code
 
 ::note{icon="i-lucide-info"}
-**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://docs.claude.com/en/docs/claude-code/quickstart) for installation instructions.
+**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://code.claude.com/docs/en/quickstart) for installation instructions.
 ::
 
 Add the server using the CLI command:

package/3.guide/3.ai/2.llms-txt.md

@@ -42,7 +42,7 @@ Nuxt provides specialized LLMs.txt files that you can reference in Cursor for be
 1. **Direct reference**: Mention the LLMs.txt URLs when asking questions
 2. Add these specific URLs to your project context using `@docs`
 
-[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/symbols)
+[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/mentions)
 
 ### Windsurf
 

package/3.guide/4.modules/3.recipes-basics.md

@@ -200,6 +200,96 @@ It is highly recommended to prefix your exports to avoid conflicts with user cod
 Note that all components, pages, composables and other files that would be normally placed in your `app/` folder need to be in `runtime/app/`. This will mean they can be type checked properly.
 ::
 
+### Add Keyed Functions
+
+Sometimes, you may need to maintain state consistency between the server and the client. Examples include Nuxt's built-in `useState` or `useAsyncData` composables. Nuxt provides a way to register such functions for automatic key injection.
+
+When a function is registered, Nuxt’s compiler automatically injects a unique key as an additional argument if the function is called with fewer than the specified number of arguments. This key remains stable between server-side rendering and client hydration.
+
+::tip
+The injected key is a hash derived from the file path and call location.
+::
+
+Use the `keyedComposables` option to register your function:
+
+```ts
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  setup (options, nuxt) {
+    const resolver = createResolver(import.meta.url)
+
+    nuxt.options.optimization.keyedComposables.push({
+      name: 'useMyState',
+      source: resolver.resolve('./runtime/composables/state'),
+      argumentLength: 2,
+    })
+  },
+})
+```
+
+The `keyedComposables` configuration accepts an array of objects with the following properties:
+
+| Property         | Type     | Description                                                                                                                |
+|------------------|----------|----------------------------------------------------------------------------------------------------------------------------|
+| `name`           | `string` | The function name. Use `'default'` for default exports (the callable name will be derived from the filename in camelCase). |
+| `source`         | `string` | Resolved path to the file where the function is defined. Supports Nuxt aliases (`~`, `@`, etc.)                            |
+| `argumentLength` | `number` | Maximum number of arguments the function accepts. When called with fewer arguments, a unique key is injected.              |
+
+For example, with `argumentLength: 2`:
+
+```ts
+useMyState() // useMyState('$HJiaryoL2y')
+useMyState('myKey') // useMyState('myKey', '$HJiaryoL2y')
+useMyState('a', 'b') // not transformed (already has 2 arguments)
+```
+
+::warning
+The key injection plugin verifies the exact resolved import source of each function call. It does not follow barrel exports. The function must be exported from the exact source file specified in the `source` property.
+
+```ts
+// ✅ Works - direct import matches the configured source
+import { useMyState } from 'my-module/runtime/composables/state'
+
+// ❌ Won't work - re-exported through a barrel file
+import { useMyState } from 'my-module/runtime/composables' // index.ts barrel
+```
+::
+
+::warning
+The function call must be statically analyzable. The compiler cannot inject keys for dynamic or indirect function calls.
+
+```ts
+import { useMyState } from 'my-module/runtime/composables/state'
+import * as composables from 'my-module/runtime/composables/state'
+
+// ✅ Works - direct function call
+useMyState()
+
+// ✅ Works - called on namespace import
+composables.useMyState()
+
+// ❌ Won't work - dynamic property access
+const name = 'useMyState'
+composables[name]()
+
+// ❌ Won't work - reassigned to a variable
+const myFn = useMyState
+myFn()
+
+// ❌ Won't work - passed as a callback
+someFunction(useMyState)
+
+// ❌ Won't work - destructured with renaming in a nested scope
+function setup () {
+  const { useMyState: localState } = composables
+  localState() // not transformed
+}
+
+// ...
+```
+::
+
 ## Add Server Routes
 
 ```ts

package/3.guide/5.recipes/3.custom-usefetch.md

@@ -10,19 +10,46 @@ The [`$fetch`](/docs/4.x/api/utils/dollarfetch) utility function (used by the [`
 
 However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call).
 
-## Custom `$fetch`
+## Recipe: API Client with Auth
 
-Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins).
+Let's say you have an external API at `https://api.nuxt.com` that requires JWT authentication via [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils), and you want to redirect to `/login` on `401` responses.
+
+```ts [app/composables/useAPI.ts]
+export const useAPI = createUseFetch({
+  baseURL: 'https://api.nuxt.com',
+  onRequest ({ options }) {
+    const { session } = useUserSession()
+    if (session.value?.token) {
+      options.headers.set('Authorization', `Bearer ${session.value.token}`)
+    }
+  },
+  async onResponseError ({ response }) {
+    if (response.status === 401) {
+      await navigateTo('/login')
+    }
+  },
+})
+```
+
+Now every call to `useAPI` automatically includes the auth header and handles 401 redirects:
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+const { data: profile } = await useAPI('/me')
+const { data: orders } = await useAPI('/orders')
+</script>
+```
+
+:read-more{to="/docs/4.x/api/composables/create-use-fetch"}
+
+## Recipe: Custom `$fetch` Instance
+
+If you need lower-level control, you can create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins) and either use it with `useAsyncData` directly or pass it to `createUseFetch`.
 
 ::note
 `$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).
 ::
 
-Let's pretend here that:
-- The main API is https://api.nuxt.com
-- We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils)
-- If the API responds with a `401` status code, we redirect the user to the `/login` page
-
 ```ts [app/plugins/api.ts]
 export default defineNuxtPlugin((nuxtApp) => {
   const { session } = useUserSession()
@@ -31,7 +58,6 @@ export default defineNuxtPlugin((nuxtApp) => {
     baseURL: 'https://api.nuxt.com',
     onRequest ({ request, options, error }) {
       if (session.value?.token) {
-        // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
         options.headers.set('Authorization', `Bearer ${session.value?.token}`)
       }
     },
@@ -42,7 +68,6 @@ export default defineNuxtPlugin((nuxtApp) => {
     },
   })
 
-  // Expose to useNuxtApp().$api
   return {
     provide: {
       api,
@@ -51,7 +76,7 @@ export default defineNuxtPlugin((nuxtApp) => {
 })
 ```
 
-With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components:
+You can then use the custom `$fetch` instance directly:
 
 ```vue [app/app.vue]
 <script setup>
@@ -61,65 +86,9 @@ const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
 ```
 
 ::callout
-Wrapping with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) **avoid double data fetching when doing server-side rendering** (server & client on hydration).
-::
-
-## Custom `useFetch`/`useAsyncData`
-
-Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`:
-
-```ts [app/composables/useAPI.ts]
-import type { UseFetchOptions } from 'nuxt/app'
-
-export function useAPI<T> (
-  url: string | (() => string),
-  options?: UseFetchOptions<T>,
-) {
-  return useFetch(url, {
-    ...options,
-    $fetch: useNuxtApp().$api as typeof $fetch,
-  })
-}
-```
-
-Let's use the new composable and have a nice and clean component:
-
-```vue [app/app.vue]
-<script setup>
-const { data: modules } = await useAPI('/modules')
-</script>
-```
-
-If you want to customize the type of any error returned, you can also do so:
-
-```ts
-import type { FetchError } from 'ofetch'
-import type { UseFetchOptions } from 'nuxt/app'
-
-interface CustomError {
-  message: string
-  status: number
-}
-
-export function useAPI<T> (
-  url: string | (() => string),
-  options?: UseFetchOptions<T>,
-) {
-  return useFetch<T, FetchError<CustomError>>(url, {
-    ...options,
-    $fetch: useNuxtApp().$api,
-  })
-}
-```
-
-::note
-This example demonstrates how to use a custom `useFetch`, but the same structure is identical for a custom `useAsyncData`.
+Wrapping with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) **avoids double data fetching when doing server-side rendering** (server & client on hydration).
 ::
 
 :link-example{to="/docs/4.x/examples/advanced/use-custom-fetch-composable"}
 
 :video-accordion{title="Watch a video about custom $fetch and Repository Pattern in Nuxt" videoId="jXH8Tr-exhI"}
-
-::note
-We are currently discussing to find a cleaner way to let you create a custom fetcher, see https://github.com/nuxt/nuxt/issues/14736.
-::

package/3.guide/5.recipes/4.sessions-and-authentication.md

@@ -47,7 +47,7 @@ Let's create a `/api/login` API route that will accept a POST request with the e
 import { z } from 'zod'
 
 const bodySchema = z.object({
-  email: z.string().email(),
+  email: z.email(),
   password: z.string().min(8),
 })
 
@@ -210,7 +210,7 @@ We've successfully set up a very basic user authentication and session managemen
 
 As next steps, you can:
 - Add authentication using the [20+ supported OAuth providers](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#supported-oauth-providers)
-- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/features/database)
+- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/database)
 - Let user signup with email & password using [password hashing](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#password-hashing)
 - Add support for [WebAuthn / Passkeys](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#webauthn-passkey)
 

package/3.guide/6.going-further/1.experimental-features.md

@@ -238,12 +238,19 @@ export default defineNuxtConfig({
 
 ## payloadExtraction
 
-Enables extraction of payloads of pages generated with `nuxt generate`.
+Controls how payload data is delivered for prerendered and cached (ISR/SWR) pages.
+
+- `'client'` - Payload is inlined in HTML for the initial server render, and extracted to `_payload.json` files for client-side navigation. This avoids a separate network request on initial load while still enabling efficient client-side navigation.
+- `true` - Payload is extracted to a separate `_payload.json` file for both the initial server render and client-side navigation.
+- `false` - Payload extraction is disabled entirely. Payload is always inlined in HTML and no `_payload.json` files are generated.
+
+The default is `true`, or `'client'` when `compatibilityVersion: 5` is set.
 
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    // Inline payload in HTML, extract for client-side navigation only
+    payloadExtraction: 'client',
   },
 })
 ```
@@ -253,7 +260,7 @@ Payload extraction also works for routes using ISR (Incremental Static Regenerat
 ```ts twoslash [nuxt.config.ts]
 export default defineNuxtConfig({
   experimental: {
-    payloadExtraction: true,
+    payloadExtraction: 'client',
   },
   routeRules: {
     // Payload files will be generated for these cached routes
@@ -303,11 +310,27 @@ export default defineNuxtConfig({
 })
 ```
 
+You can also pass an object to configure [view transition types](/docs/4.x/getting-started/transitions#view-transition-types), which allow different CSS animations based on the type of navigation:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    viewTransition: {
+      enabled: true,
+      types: ['slide'],
+    },
+  },
+})
+```
+
 :link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
 
 ::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" target="_blank"}
 Read more about the **View Transition API**.
 ::
+::read-more{icon="i-simple-icons-google" to="https://developer.chrome.com/blog/view-transitions-update-io24" target="_blank"}
+Read more about the **View Transition API**.
+::
 
 ## writeEarlyHints
 
@@ -370,7 +393,11 @@ Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/uti
 You can even get typed params within a page by using `const route = useRoute('route-name')`.
 
 ::important
-If you use `pnpm` without `shamefully-hoist=true`, you will need to have `unplugin-vue-router` installed as a devDependency in order for this feature to work.
+If you use `pnpm` without `shamefully-hoist=true`, you will need to add `unplugin-vue-router` as a hoist pattern in your `pnpm-workspace.yaml` in order for this feature to work.
+```yaml
+publicHoistPattern:
+  - "unplugin-vue-router"
+```
 ::
 
 :video-accordion{title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" videoId="SXk-L19gTZk"}
@@ -603,6 +630,30 @@ But in order to auto-import it, you would need to use `SomeFolderMyComponent`.
 
 By setting `experimental.normalizeComponentNames`, these two values match, and Vue will generate a component name that matches the Nuxt pattern for component naming.
 
+## normalizePageNames
+
+Ensure that page component names match their route names. This sets the `__name` property on page components so that Vue's `<KeepAlive>` can correctly identify them by name.
+
+By default, Vue assigns component names based on the filename. For example, `pages/foo/index.vue` and `pages/bar/index.vue` would both have the component name `index`. This makes name-based `<KeepAlive>` filtering unreliable because multiple pages share the same name.
+
+With `normalizePageNames` enabled, page components are named after their route (e.g. `foo` and `bar`), so you can use `<KeepAlive>` with `include`/`exclude` without manually adding `defineOptions({ name: '...' })` to each page.
+
+This flag is enabled when `future.compatibilityVersion` is set to `5` or higher, but you can disable this feature:
+
+```ts twoslash [nuxt.config.ts]
+export default defineNuxtConfig({
+  experimental: {
+    normalizePageNames: false,
+  },
+})
+```
+
+```vue [app.vue]
+<template>
+  <NuxtPage :keepalive="{ include: ['foo'] }" />
+</template>
+```
+
 ## spaLoadingTemplateLocation
 
 When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).
@@ -722,7 +773,9 @@ export default defineNuxtConfig({
 
 ## decorators
 
-This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
+This option enables decorator syntax across your entire Nuxt/Nitro app.
+
+When using the Vite builder (default), decorators are lowered via [Babel](https://babeljs.io/) using [`@babel/plugin-proposal-decorators`](https://babeljs.io/docs/babel-plugin-proposal-decorators). When using the webpack or rspack builders, decorators are lowered via [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).
 
 For a long time, TypeScript has had support for decorators via `compilerOptions.experimentalDecorators`. This implementation predated the TC39 standardization process. Now, decorators are a [Stage 3 Proposal](https://github.com/tc39/proposal-decorators), and supported without special configuration in TS 5.0+ (see https://github.com/microsoft/TypeScript/pull/52582 and https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators).
 
@@ -742,6 +795,24 @@ export default defineNuxtConfig({
 })
 ```
 
+When using the Vite builder or the Nitro server build, you will need to install additional Babel packages as dev dependencies:
+
+::code-group
+```bash [npm]
+npm install -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [pnpm]
+pnpm add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+```bash [yarn]
+yarn add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx
+```
+::
+
+::tip
+Nuxt will prompt you to install these automatically if they are not already present.
+::
+
 ```ts [app/app.vue]
 function something (_method: () => unknown) {
   return () => 'decorated'
@@ -778,11 +849,16 @@ export default defineNuxtConfig({
       useAsyncData: {
         deep: true,
       },
+      useState: {
+        resetOnClear: true,
+      },
     },
   },
 })
 ```
 
+The `useState.resetOnClear` option controls whether [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) resets state to its initial value (provided by the `init` function of [`useState`](/docs/4.x/api/composables/use-state)) instead of setting it to `undefined`. This defaults to `true` with `compatibilityVersion: 5`.
+
 ## purgeCachedData
 
 Whether to clean up Nuxt static and asyncData caches on route navigation.

package/3.guide/6.going-further/2.hooks.md

@@ -57,7 +57,7 @@ Explore all available App hooks.
 
 These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.
 
-```ts [~/server/plugins/test.ts]
+```ts [~~/server/plugins/test.ts]
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook('render:html', (html, { event }) => {
     console.log('render:html', html)

package/4.api/1.components/12.nuxt-route-announcer.md

@@ -52,3 +52,7 @@ To achieve full customization, you can implement your own one based on [its sour
 ::callout
 You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/4.x/api/composables/use-route-announcer), which allows you to set a custom announcement message.
 ::
+
+::callout
+For announcing in-page content changes (form validation, toast notifications, loading states, etc.), use the [`<NuxtAnnouncer>`](/docs/4.x/api/components/nuxt-announcer) component with the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable instead.
+::

package/4.api/1.components/14.nuxt-announcer.md

@@ -0,0 +1,81 @@
+---
+title: '<NuxtAnnouncer>'
+description: 'The <NuxtAnnouncer> component adds a hidden element to announce dynamic content changes to assistive technologies.'
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts
+    size: xs
+---
+
+::important
+This component is available in Nuxt v3.17+.
+::
+
+## Usage
+
+Add `<NuxtAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enable announcing dynamic content changes to screen readers. This is useful for form validation, toast notifications, loading states, and other in-page updates.
+
+```vue [app/app.vue]
+<template>
+  <NuxtAnnouncer />
+  <NuxtRouteAnnouncer />
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>
+```
+
+Then use the [`useAnnouncer`](/docs/4.x/api/composables/use-announcer) composable anywhere in your app to announce messages:
+
+```vue [app/pages/contact.vue]
+<script setup lang="ts">
+const { polite, assertive } = useAnnouncer()
+
+async function submitForm () {
+  try {
+    await $fetch('/api/contact', { method: 'POST', body: formData })
+    polite('Message sent successfully')
+  } catch (error) {
+    assertive('Error: Failed to send message')
+  }
+}
+</script>
+```
+
+## Slots
+
+You can pass custom HTML or components through the announcer's default slot.
+
+```vue
+<template>
+  <NuxtAnnouncer>
+    <template #default="{ message }">
+      <p>{{ message }}</p>
+    </template>
+  </NuxtAnnouncer>
+</template>
+```
+
+## Props
+
+- `atomic`: Controls if screen readers announce only changes or the entire content. Set to true for full content readouts on updates, false for changes only. (default `true`)
+- `politeness`: Sets the default urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)
+
+## Differences from `<NuxtRouteAnnouncer>`
+
+| Aspect | `<NuxtRouteAnnouncer>` | `<NuxtAnnouncer>` |
+|--------|------------------------|-------------------|
+| **Purpose** | Announces route/page changes | Announces any dynamic content |
+| **Trigger** | Automatic on navigation | Manual via `polite()`/`assertive()` |
+| **Message source** | Page `<title>` | Developer-provided |
+| **atomic default** | `false` | `true` |
+
+::callout
+This component is optional. :br
+To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-announcer.ts).
+::
+
+::callout
+You can hook into the underlying announcer instance using [the `useAnnouncer` composable](/docs/4.x/api/composables/use-announcer), which allows you to set custom announcement messages.
+::

package/4.api/1.components/3.nuxt-layout.md

@@ -86,6 +86,35 @@ console.log(layoutCustomProps.title) // I am a custom layout
 </script>
 ```
 
+## Layout Props from Page Meta
+
+When using [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) with the object syntax for `layout`, props are automatically passed to the layout component. The layout can receive them with `defineProps`:
+
+```vue [app/pages/dashboard.vue]
+<script setup lang="ts">
+definePageMeta({
+  layout: {
+    name: 'admin',
+    props: {
+      sidebar: true,
+    },
+  },
+})
+</script>
+```
+
+```vue [app/layouts/admin.vue]
+<script setup lang="ts">
+const props = defineProps<{
+  sidebar?: boolean
+}>()
+</script>
+```
+
+::read-more{to="/docs/4.x/directory-structure/app/layouts#passing-props-to-layouts"}
+Read more about passing props to layouts.
+::
+
 ## Transitions
 
 `<NuxtLayout />` renders incoming content via `<slot />`, which is then wrapped around Vue’s `<Transition />` component to activate layout transition. For this to work as expected, it is recommended that `<NuxtLayout />` is **not** the root element of the page component.