diff --git a/docs/content/3.api/1.composables/use-head.md b/docs/content/3.api/1.composables/use-head.md index 411e50a7dff..51a9db990da 100644 --- a/docs/content/3.api/1.composables/use-head.md +++ b/docs/content/3.api/1.composables/use-head.md @@ -1,48 +1,201 @@ # `useHead` -::ReadMore{link="/guide/features/head-management"} +Nuxt provides the `useHead` composable to add and customize the head properties of individual pages of your Nuxt app. `useHead` uses [@vueuse/head](https://github.com/vueuse/head) under the hood. -Nuxt provides a composable to update the head properties of your page with an [`MetaObject`](/api/composables/use-head/#metaobject) of meta properties with keys corresponding to meta tags: +::alert{icon=👉} +**`useHead` must be placed within the `setup` function**. +:: -`title`, `base`, `script`, `noscript`, `style`, `meta` and `link`, as well as `htmlAttrs` and `bodyAttrs`. Alternatively, you can pass a function returning the object for reactive metadata. +## Type -```js -useHead(options: MetaObject) +```ts +useHead(meta: Computable): void + +interface MetaObject extends Record { + charset?: string + viewport?: string + meta?: Array> + link?: Array> + style?: Array> + script?: Array> + noscript?: Array> + titleTemplate?: string | ((title: string) => string) + title?: string + bodyAttrs?: Record + htmlAttrs?: Record +} ``` -::alert{icon=👉} -**`useHead` only works during `setup`**. +Application-wide configuration of the head metadata is possible through [nuxt.config](/api/configuration/nuxt.config#head), or by placing the `useHead` in the `app.vue` file. + +::alert{type=info} +The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. `meta` parameter can also accept a function returning an object to make the entire object reactive. :: -## Example - -The example below changes the website's title in the `meta` and inserts a Google Font using the `link` property. - -```js -export default { - setup () { - useHead({ - meta: [ - { name: 'title' content: 'Nuxt 3 - The Hybrid Vue Framework' } - ], - link: [ - { rel: 'preconnect', href: 'https://fonts.googleapis.com' }, - { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }, - { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', crossorigin: '' }, - ] - }) - } -} +## Parameters + +### `meta` + +**Type**: `MetaObject` + +An object accepting the following head metadata: + +- `charset` + + **Type**: `string` + + **Default**: `utf-8` + + Specifies character encoding for the HTML document. + +- `viewport` + + **Type**: `string` + + **Default**: `width=device-width, initial-scale=1` + + Configures the viewport (the user's visible area of a web page). + +- `meta` + + **Type**: `Array>` + + **Default**: `width=device-width, initial-scale=1` + + Each element in the array is mapped to a newly-created `` tag, where object properties are mapped to the corresponding attributes. + +- `link` + + **Type**: `Array>` + + Each element in the array is mapped to a newly-created `` tag, where object properties are mapped to the corresponding attributes. + +- `style` + + **Type**: `Array>` + + Each element in the array is mapped to a newly-created `