@nuxt/docs 3.20.0 → 3.20.2

package/{2.guide/3.going-further → 3.guide/4.going-further}/3.modules.md

@@ -117,7 +117,7 @@ Nuxt Modules come with a variety of powerful APIs and patterns allowing them to
 We can consider two kinds of Nuxt Modules:
 
 - published modules are distributed on npm - you can see a list of some community modules on [the Nuxt website](/modules).
-- "local" modules, they exist within a Nuxt project itself, either [inlined in Nuxt config](/docs/3.x/api/nuxt-config#modules) or as part of [the `modules` directory](/docs/3.x/guide/directory-structure/modules).
+- "local" modules, they exist within a Nuxt project itself, either [inlined in Nuxt config](/docs/3.x/api/nuxt-config#modules) or as part of [the `modules` directory](/docs/3.x/directory-structure/modules).
 
 In either case, their anatomy is similar.
 
@@ -224,7 +224,7 @@ Modules, like everything in a Nuxt configuration, aren't included in your applic
 Inside the runtime directory, you can provide any kind of assets related to the Nuxt App:
 - Vue components
 - Composables
-- [Nuxt plugins](/docs/3.x/guide/directory-structure/plugins)
+- [Nuxt plugins](/docs/3.x/directory-structure/plugins)
 
 To the [server engine](/docs/3.x/guide/concepts/server-engine), Nitro:
 - API routes
@@ -774,7 +774,7 @@ An example of such a workflow is available on [the module starter](https://githu
 
 Having a playground Nuxt application to test your module when developing it is really useful. [The module starter integrates one for that purpose](#how-to-develop).
 
-You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
+You can test your module with other Nuxt applications (applications that are not part of your module repository) locally. To do so, you can use [`npm pack`](https://docs.npmjs.com/cli/commands/npm-pack/) command, or your package manager equivalent, to create a tarball from your module. Then in your test project, you can add your module to `package.json` packages as: `"my-module": "file:/path/to/tarball.tgz"`.
 
 After that, you should be able to reference `my-module` like in any regular project.
 

package/{2.guide/3.going-further → 3.guide/4.going-further}/6.nuxt-app.md

@@ -23,7 +23,7 @@ Jump over the `NuxtApp` interface documentation.
 
 Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.
 
-Currently, the Nuxt context is only accessible in [plugins](/docs/3.x/guide/directory-structure/plugins), [Nuxt hooks](/docs/3.x/guide/going-further/hooks), [Nuxt middleware](/docs/3.x/guide/directory-structure/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
+Currently, the Nuxt context is only accessible in [plugins](/docs/3.x/directory-structure/plugins), [Nuxt hooks](/docs/3.x/guide/going-further/hooks), [Nuxt middleware](/docs/3.x/directory-structure/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup.html) (in pages and components).
 
 If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/3.x/api/composables/use-nuxt-app#runwithcontext).
 

package/{2.guide/3.going-further → 3.guide/4.going-further}/7.layers.md

@@ -7,7 +7,7 @@ Nuxt layers are a powerful feature that you can use to share and reuse partial N
 
 :read-more{to="/docs/getting-started/layers"}
 
-A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/3.x/guide/directory-structure/nuxt-config) file to indicate it is a layer.
+A minimal Nuxt layer directory should contain a [`nuxt.config.ts`](/docs/3.x/directory-structure/nuxt-config) file to indicate it is a layer.
 
 ```ts [base/nuxt.config.ts]
 export default defineNuxtConfig({})
@@ -15,16 +15,16 @@ export default defineNuxtConfig({})
 
 Additionally, certain other files in the layer directory will be auto-scanned and used by Nuxt for the project extending this layer.
 
-- [`components/*`](/docs/3.x/guide/directory-structure/components)   - Extend the default components
-- [`composables/*`](/docs/3.x/guide/directory-structure/composables)  - Extend the default composables
-- [`layouts/*`](/docs/3.x/guide/directory-structure/layouts)  - Extend the default layouts
-- [`middleware/*`](/docs/3.x/guide/directory-structure/middleware)  - Extend the default middleware
-- [`pages/*`](/docs/3.x/guide/directory-structure/pages)        - Extend the default pages
-- [`plugins/*`](/docs/3.x/guide/directory-structure/plugins)        - Extend the default plugins
-- [`server/*`](/docs/3.x/guide/directory-structure/server)       - Extend the default server endpoints & middleware
-- [`utils/*`](/docs/3.x/guide/directory-structure/utils)   - Extend the default utils
-- [`nuxt.config.ts`](/docs/3.x/guide/directory-structure/nuxt-config)- Extend the default nuxt config
-- [`app.config.ts`](/docs/3.x/guide/directory-structure/app-config)  - Extend the default app config
+- [`components/*`](/docs/3.x/directory-structure/components)   - Extend the default components
+- [`composables/*`](/docs/3.x/directory-structure/composables)  - Extend the default composables
+- [`layouts/*`](/docs/3.x/directory-structure/layouts)  - Extend the default layouts
+- [`middleware/*`](/docs/3.x/directory-structure/middleware)  - Extend the default middleware
+- [`pages/*`](/docs/3.x/directory-structure/pages)        - Extend the default pages
+- [`plugins/*`](/docs/3.x/directory-structure/plugins)        - Extend the default plugins
+- [`server/*`](/docs/3.x/directory-structure/server)       - Extend the default server endpoints & middleware
+- [`utils/*`](/docs/3.x/directory-structure/utils)   - Extend the default utils
+- [`nuxt.config.ts`](/docs/3.x/directory-structure/nuxt-config)- Extend the default nuxt config
+- [`app.config.ts`](/docs/3.x/directory-structure/app-config)  - Extend the default app config
 
 ## Basic Example
 
@@ -68,29 +68,46 @@ Additionally, certain other files in the layer directory will be auto-scanned an
 
 ## Layer Priority
 
-When extending from multiple layers, it's important to understand the priority order:
+When extending from multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.
 
-1. **Layers in `extends`** - earlier entries have higher priority (first overrides second)
-2. **Auto-scanned local layers** from `~~/layers` directory in alphabetical order (Z overrides A)
-3. **Your project** has the highest priority in the stack - it will always override other layers
+The priority order from highest to lowest is:
 
-For example:
+1. **Your project files** - always have the highest priority
+2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
+3. **Layers in `extends`** config - first entry has higher priority than second
+
+### When to Use Each
+
+- **`extends`** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory
+- **`~~/layers` directory** - Use for local layers that are part of your project
+
+::tip
+If you need to control the order of auto-scanned layers, you can prefix them with numbers: `~/layers/1.z-layer`, `~/layers/2.a-layer`. This way `2.a-layer` will have higher priority than `1.z-layer`.
+::
+
+### Example
 
 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   extends: [
-    // Highest priority (among extends)
-    './layers/base',
-    // Medium priority
-    './layers/theme',
-    // Lower priority
-    './layers/custom',
+    // Local layer outside the project
+    '../base',
+    // NPM package
+    '@my-themes/awesome',
+    // Remote repository
+    'github:my-themes/awesome#v1',
   ],
-  // Your project has the highest priority
 })
 ```
 
-If you also have auto-scanned layers like `~~/layers/a` and `~~/layers/z`, the complete override order would be: `base` > `theme` > `custom` > `z` > `a` > your project.
+If you also have `~~/layers/custom`, the priority order is:
+- Your project files (highest)
+- `~~/layers/custom`
+- `../base`
+- `@my-themes/awesome`
+- `github:my-themes/awesome#v1` (lowest)
+
+This means your project files will override any layer, and `~~/layers/custom` will override anything in `extends`.
 
 ## Starter Template
 

package/{3.api → 4.api}/1.components/12.nuxt-route-announcer.md

@@ -16,7 +16,7 @@ This component is available in Nuxt v3.12+.
 
 ## Usage
 
-Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/3.x/guide/directory-structure/app) or [`layouts/`](/docs/3.x/guide/directory-structure/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
+Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/3.x/directory-structure/app) or [`layouts/`](/docs/3.x/directory-structure/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.
 
 ```vue [app.vue]
 <template>

package/{3.api → 4.api}/1.components/2.nuxt-page.md

@@ -8,7 +8,7 @@ links:
     size: xs
 ---
 
-`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/3.x/guide/directory-structure/pages) directory.
+`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`pages/`](/docs/3.x/directory-structure/pages) directory.
 
 ::note
 `<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/RouterViewProps.html#interface-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.

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

@@ -22,7 +22,7 @@ You can use `<NuxtLayout />` component to activate the `default` layout on `app.
 
 ## Props
 
-- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/3.x/guide/directory-structure/layouts) directory.
+- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/3.x/directory-structure/layouts) directory.
   - **type**: `string`
   - **default**: `default`
 
@@ -55,7 +55,7 @@ Please note the layout name is normalized to kebab-case, so if your layout file
 Read more about dynamic layouts.
 ::
 
-- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/3.x/guide/directory-structure/layouts) directory.
+- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`layouts/`](/docs/3.x/directory-structure/layouts) directory.
   - **type**: `string`
   - **default**: `null`
 

package/{3.api → 4.api}/1.components/5.nuxt-loading-indicator.md

@@ -10,7 +10,7 @@ links:
 
 ## Usage
 
-Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/3.x/guide/directory-structure/app) or [`layouts/`](/docs/3.x/guide/directory-structure/layouts).
+Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/3.x/directory-structure/app) or [`layouts/`](/docs/3.x/directory-structure/layouts).
 
 ```vue [app.vue]
 <template>

package/{3.api → 4.api}/2.composables/use-async-data.md

@@ -18,9 +18,9 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
 
 ```vue [pages/index.vue]
 <script setup lang="ts">
-const { data, status, error, refresh, clear } = await useAsyncData(
+const { data, status, pending, error, refresh, clear } = await useAsyncData(
   'mountains',
-  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
 )
 </script>
 ```
@@ -30,7 +30,7 @@ If you're using a custom useAsyncData wrapper, do not await it in the composable
 ::
 
 ::note
-`data`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
+`data`, `status`, `pending` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
 ::
 
 ### Watch Params
@@ -42,10 +42,11 @@ The built-in `watch` option allows automatically rerunning the fetcher function
 const page = ref(1)
 const { data: posts } = await useAsyncData(
   'posts',
-  () => $fetch('https://fakeApi.com/posts', {
+  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
     params: {
       page: page.value,
     },
+    signal,
   }), {
     watch: [page],
   },
@@ -70,6 +71,64 @@ const { data: user } = useAsyncData(
 </script>
 ```
 
+### Make your `handler` abortable
+
+You can make your `handler` function abortable by using the `signal` provided in the second argument. This is useful for cancelling requests when they are no longer needed, such as when a user navigates away from a page. `$fetch` natively supports abort signals.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh()
+
+clear() // will cancel the latest pending handler
+```
+
+You can also pass an `AbortSignal` to the `refresh`/`execute` function to cancel individual requests manually.
+
+```ts
+const { refresh } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+let abortController: AbortController | undefined
+
+function handleUserAction () {
+  abortController = new AbortController()
+  refresh({ signal: abortController.signal })
+}
+
+function handleCancel () {
+  abortController?.abort() // aborts the ongoing refresh request
+}
+```
+
+If your `handler` function does not support abort signals, you can implement your own abort logic using the `signal` provided.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => {
+    return new Promise((resolve, reject) => {
+      signal?.addEventListener('abort', () => {
+        reject(new Error('Request aborted'))
+      })
+      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
+    })
+  },
+)
+```
+
+The handler signal will be aborted when:
+
+- A new request is made with `dedupe: 'cancel'`
+- The `clear` function is called
+- The `options.timeout` duration is exceeded
+
 ::warning
 [`useAsyncData`](/docs/3.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/3.x/api/composables/use-async-data).
 ::
@@ -116,7 +175,7 @@ You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `u
 
 ### Shared State and Option Consistency
 
-When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires option consistency.
+When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error`, `status` and `pending` refs. This ensures consistency across components but requires option consistency.
 
 The following options **must be consistent** across all calls with the same key:
 - `handler` function
@@ -135,12 +194,12 @@ The following options **can differ** without triggering warnings:
 
 ```ts
 // ❌ This will trigger a development warning
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
 
 // ✅ This is allowed
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
 ```
 
 ::tip
@@ -159,6 +218,7 @@ Keyed state created using `useAsyncData` can be retrieved across your Nuxt appli
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
+- `pending`: a `Ref<boolean>` that is `true` while the request is in progress.
 - `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `null`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
@@ -170,14 +230,16 @@ If you have not fetched data on the server (for example, with `server: false`),
 ## Type
 
 ```ts [Signature]
+export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>
+
 export function useAsyncData<DataT, DataE> (
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
-  options?: AsyncDataOptions<DataT>
+  handler: AsyncDataHandler<DataT>,
+  options?: AsyncDataOptions<DataT>,
 ): Promise<AsyncData<DataT, DataE>>
 
 type AsyncDataOptions<DataT> = {
@@ -206,6 +268,7 @@ type AsyncData<DataT, ErrorT> = {
   clear: () => void
   error: Ref<ErrorT | null>
   status: Ref<AsyncDataRequestStatus>
+  pending: Ref<boolean>
 }
 
 interface AsyncDataExecuteOptions {

package/{3.api → 4.api}/2.composables/use-cookie.md

@@ -42,7 +42,7 @@ export interface CookieRef<T> extends Ref<T> {}
 
 export function useCookie<T = string | null | undefined> (
   name: string,
-  options?: CookieOptions<T>
+  options?: CookieOptions<T>,
 ): CookieRef<T>
 ```
 

package/{3.api → 4.api}/2.composables/use-fetch.md

@@ -128,7 +128,7 @@ searchQuery.value = 'new search'
 ```ts [Signature]
 export function useFetch<DataT, ErrorT> (
   url: string | Request | Ref<string | Request> | (() => string | Request),
-  options?: UseFetchOptions<DataT>
+  options?: UseFetchOptions<DataT>,
 ): Promise<AsyncData<DataT, ErrorT>>
 
 type UseFetchOptions<DataT> = {

package/{3.api → 4.api}/2.composables/use-head-safe.md

@@ -8,28 +8,12 @@ links:
     size: xs
 ---
 
-The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/3.x/api/composables/use-head) composable that restricts the input to only allow safe values.
-
 ## Usage
 
-You can pass all the same values as [`useHead`](/docs/3.x/api/composables/use-head)
-
-```ts
-useHeadSafe({
-  script: [
-    { id: 'xss-script', innerHTML: 'alert("xss")' },
-  ],
-  meta: [
-    { 'http-equiv': 'refresh', 'content': '0;javascript:alert(1)' },
-  ],
-})
-// Will safely generate
-// <script id="xss-script"></script>
-// <meta content="0;javascript:alert(1)">
-```
+The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/3.x/api/composables/use-head) composable that restricts the input to only allow safe values. This is the recommended way to manage head data when working with user input, as it prevents XSS attacks by sanitizing potentially dangerous attributes.
 
-::read-more{to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe" target="_blank"}
-Read more on the `Unhead` documentation.
+::warning
+When using `useHeadSafe`, potentially dangerous attributes like `innerHTML` in scripts or `http-equiv` in meta tags are automatically stripped out to prevent XSS attacks. Use this composable whenever you're working with user-generated content.
 ::
 
 ## Type
@@ -38,7 +22,9 @@ Read more on the `Unhead` documentation.
 export function useHeadSafe (input: MaybeComputedRef<HeadSafe>): void
 ```
 
-The list of allowed values is:
+### Allowed Attributes
+
+The following attributes are whitelisted for each head element type:
 
 ```ts
 const WhitelistAttributes = {
@@ -53,3 +39,34 @@ const WhitelistAttributes = {
 ```
 
 See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/safeSchema.ts) for more detailed types.
+
+## Parameters
+
+`input`: A `MaybeComputedRef<HeadSafe>` object containing head data. You can pass all the same values as [`useHead`](/docs/3.x/api/composables/use-head), but only safe attributes will be rendered.
+
+## Return Values
+
+This composable does not return any value.
+
+## Example
+
+```vue [app/pages/user-profile.vue]
+<script setup lang="ts">
+// User-generated content that might contain malicious code
+const userBio = ref('<script>alert("xss")<' + '/script>')
+
+useHeadSafe({
+  title: `User Profile`,
+  meta: [
+    {
+      name: 'description',
+      content: userBio.value, // Safely sanitized
+    },
+  ],
+})
+</script>
+```
+
+::read-more{to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe" target="_blank"}
+Read more on the `Unhead` documentation.
+::

package/4.api/2.composables/use-head.md

@@ -0,0 +1,169 @@
+---
+title: useHead
+description: useHead customizes the head properties of individual pages of your Nuxt app.
+links:
+  - label: Source
+    icon: i-simple-icons-github
+    to: https://github.com/unjs/unhead/blob/main/packages/vue/src/composables.ts
+    size: xs
+---
+
+## Usage
+
+The `useHead` composable allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). It lets you customize the meta tags, links, scripts, and other elements in the `<head>` section of your HTML document.
+
+```vue [app/app.vue]
+<script setup lang="ts">
+useHead({
+  title: 'My App',
+  meta: [
+    { name: 'description', content: 'My amazing site.' },
+  ],
+  bodyAttrs: {
+    class: 'test',
+  },
+  script: [{ innerHTML: 'console.log(\'Hello world\')' }],
+})
+</script>
+```
+
+::warning
+If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/3.x/api/composables/use-head-safe).
+::
+
+::note
+The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. The `meta` parameter can also accept a function returning an object to make the entire object reactive.
+::
+
+## Type
+
+```ts [Signature]
+export function useHead (meta: MaybeComputedRef<MetaObject>): void
+
+interface MetaObject {
+  title?: string
+  titleTemplate?: string | ((title?: string) => string)
+  base?: Base
+  link?: Link[]
+  meta?: Meta[]
+  style?: Style[]
+  script?: Script[]
+  noscript?: Noscript[]
+  htmlAttrs?: HtmlAttributes
+  bodyAttrs?: BodyAttributes
+}
+```
+
+See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.
+
+## Parameters
+
+`meta`: An object accepting head metadata properties to customize the page's `<head>` section. All properties support reactive values (`ref`, `computed`, `reactive`) or can be a function returning the metadata object.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `title` | `string` | Sets the page title. |
+| `titleTemplate` | `string \| ((title?: string) => string)` | Configures a dynamic template to customize the page title. Can be a string with `%s` placeholder or a function. |
+| `base` | `Base` | Sets the `<base>` tag for the document. |
+| `link` | `Link[]` | Array of link objects. Each element is mapped to a `<link>` tag, where object properties correspond to HTML attributes. |
+| `meta` | `Meta[]` | Array of meta objects. Each element is mapped to a `<meta>` tag, where object properties correspond to HTML attributes. |
+| `style` | `Style[]` | Array of style objects. Each element is mapped to a `<style>` tag, where object properties correspond to HTML attributes. |
+| `script` | `Script[]` | Array of script objects. Each element is mapped to a `<script>` tag, where object properties correspond to HTML attributes. |
+| `noscript` | `Noscript[]` | Array of noscript objects. Each element is mapped to a `<noscript>` tag, where object properties correspond to HTML attributes. |
+| `htmlAttrs` | `HtmlAttributes` | Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute. |
+| `bodyAttrs` | `BodyAttributes` | Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute. |
+
+## Return Values
+
+This composable does not return any value. It registers the head metadata with Unhead, which manages the actual DOM updates.
+
+## Examples
+
+### Basic Meta Tags
+
+```vue [app/pages/about.vue]
+<script setup lang="ts">
+useHead({
+  title: 'About Us',
+  meta: [
+    { name: 'description', content: 'Learn more about our company' },
+    { property: 'og:title', content: 'About Us' },
+    { property: 'og:description', content: 'Learn more about our company' },
+  ],
+})
+</script>
+```
+
+### Reactive Meta Tags
+
+```vue [app/pages/profile.vue]
+<script setup lang="ts">
+const profile = ref({ name: 'John Doe' })
+
+useHead({
+  title: computed(() => profile.value.name),
+  meta: [
+    {
+      name: 'description',
+      content: computed(() => `Profile page for ${profile.value.name}`),
+    },
+  ],
+})
+</script>
+```
+
+### Using a Function for Full Reactivity
+
+```vue [app/pages/dynamic.vue]
+<script setup lang="ts">
+const count = ref(0)
+
+useHead(() => ({
+  title: `Count: ${count.value}`,
+  meta: [
+    { name: 'description', content: `Current count is ${count.value}` },
+  ],
+}))
+</script>
+```
+
+### Adding External Scripts and Styles
+
+```vue [app/pages/external.vue]
+<script setup lang="ts">
+useHead({
+  link: [
+    {
+      rel: 'stylesheet',
+      href: 'https://cdn.example.com/styles.css',
+    },
+  ],
+  script: [
+    {
+      src: 'https://cdn.example.com/script.js',
+      async: true,
+    },
+  ],
+})
+</script>
+```
+
+### Body and HTML Attributes
+
+```vue [app/pages/themed.vue]
+<script setup lang="ts">
+const isDark = ref(true)
+
+useHead({
+  htmlAttrs: {
+    lang: 'en',
+    class: computed(() => isDark.value ? 'dark' : 'light'),
+  },
+  bodyAttrs: {
+    class: 'themed-page',
+  },
+})
+</script>
+```
+
+:read-more{to="/docs/3.x/getting-started/seo-meta"}