mirror of
https://github.com/nuxt/nuxt.git
synced 2024-11-11 08:33:53 +00:00
docs(api): enhance useHead composable (#7072)
Co-authored-by: Damian Głowala <48835293+DamianGlowala@users.noreply.github.com>
This commit is contained in:
Krutie Patel
GitHub
parent
5650927c34
commit
664e5702af
@ -1,48 +1,201 @@
|
||||
# `useHead`
|
||||
|
||||
::ReadMore{link="/guide/features/head-management"}
|
||||
|
||||
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:
|
||||
|
||||
`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.
|
||||
|
||||
```js
|
||||
useHead(options: MetaObject)
|
||||
```
|
||||
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.
|
||||
|
||||
::alert{icon=👉}
|
||||
**`useHead` only works during `setup`**.
|
||||
**`useHead` must be placed within the `setup` function**.
|
||||
::
|
||||
|
||||
## Example
|
||||
## Type
|
||||
|
||||
The example below changes the website's title in the `meta` and inserts a Google Font using the `link` property.
|
||||
```ts
|
||||
useHead(meta: Computable<MetaObject>): void
|
||||
|
||||
```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: '' },
|
||||
]
|
||||
})
|
||||
}
|
||||
interface MetaObject extends Record<string, any> {
|
||||
charset?: string
|
||||
viewport?: string
|
||||
meta?: Array<Record<string, any>>
|
||||
link?: Array<Record<string, any>>
|
||||
style?: Array<Record<string, any>>
|
||||
script?: Array<Record<string, any>>
|
||||
noscript?: Array<Record<string, any>>
|
||||
titleTemplate?: string | ((title: string) => string)
|
||||
title?: string
|
||||
bodyAttrs?: Record<string, any>
|
||||
htmlAttrs?: Record<string, any>
|
||||
}
|
||||
```
|
||||
|
||||
## `MetaObject`
|
||||
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.
|
||||
|
||||
* **charset**: the character encoding in which the document is encoded => `<meta charset="<value>" />` (default: `'utf-8'`)
|
||||
* **viewport**: configuration of the viewport (the area of the window in which web content can be seen) => `<meta name="viewport" content="<value>" />` (default: `'width=device-width, initial-scale=1'`)
|
||||
* **meta**: array, each item maps to a newly-created `<meta>` element, where object properties map to attributes.
|
||||
* **link**: array, each item maps to a newly-created `<link>` element, where object properties map to attributes.
|
||||
* **style**: array, each item maps to a newly-created `<style>` element, where object properties map to attributes.
|
||||
* **script**: array, each item maps to a newly-created `<script>` element, where object properties map to attributes.
|
||||
* **noscript**: array, each item maps to a newly-created `<noscript>` element, where object properties map to attributes.
|
||||
::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.
|
||||
::
|
||||
|
||||
All elements in the meta object are optional. You can also pass only single values.
|
||||
## 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<Record<string, any>>`
|
||||
|
||||
**Default**: `width=device-width, initial-scale=1`
|
||||
|
||||
Each element in the array is mapped to a newly-created `<meta>` tag, where object properties are mapped to the corresponding attributes.
|
||||
|
||||
- `link`
|
||||
|
||||
**Type**: `Array<Record<string, any>>`
|
||||
|
||||
Each element in the array is mapped to a newly-created `<link>` tag, where object properties are mapped to the corresponding attributes.
|
||||
|
||||
- `style`
|
||||
|
||||
**Type**: `Array<Record<string, any>>`
|
||||
|
||||
Each element in the array is mapped to a newly-created `<style>` tag, where object properties are mapped to the corresponding attributes.
|
||||
|
||||
- `script`
|
||||
|
||||
**Type**: `Array<Record<string, any>>`
|
||||
|
||||
Each element in the array is mapped to a newly-created `<script>` tag, where object properties are mapped to the corresponding attributes.
|
||||
|
||||
- `noscript`
|
||||
|
||||
**Type**: `Array<Record<string, any>>`
|
||||
|
||||
Each element in the array is mapped to a newly-created `<noscript>` tag, where object properties are mapped to the corresponding attributes.
|
||||
|
||||
- `titleTemplate`
|
||||
|
||||
**Type**: `string` | `((title: string) => string)`
|
||||
|
||||
Configures dynamic template to customize the page title on an individual page.
|
||||
|
||||
- `title`
|
||||
|
||||
**Type**: `string`
|
||||
|
||||
Sets static page title on an individual page.
|
||||
|
||||
- `bodyAttrs`
|
||||
|
||||
**Type**: `Record<string, any>`
|
||||
|
||||
Sets attributes of the `<body>` tag. Each object property is mapped to the corresponding attribute.
|
||||
|
||||
- `htmlAttrs`
|
||||
|
||||
**Type**: `Record<string, any>`
|
||||
|
||||
Sets attributes of the `<html>` tag. Each object property is mapped to the corresponding attribute.
|
||||
|
||||
## Examples
|
||||
|
||||
### Customize Metadata
|
||||
|
||||
The example below changes the website's `title` and `description` using `meta` option of the `useHead` composable:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
const title = ref('My App')
|
||||
const description = ref('My amazing Nuxt app')
|
||||
|
||||
useHead({
|
||||
title,
|
||||
meta: [
|
||||
{
|
||||
name: 'description',
|
||||
content: description
|
||||
}
|
||||
]
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
### Add Dynamic Title
|
||||
|
||||
In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app:
|
||||
|
||||
```vue [app.vue]
|
||||
<script setup>
|
||||
useHead({
|
||||
// as a string,
|
||||
// where `%s` is replaced with the title
|
||||
titleTemplate: '%s - Site Title',
|
||||
// ... or as a function
|
||||
titleTemplate: (productCategory) => {
|
||||
return productCategory
|
||||
? `${productCategory} - Site Title`
|
||||
: 'Site Title'
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
`nuxt.config` is also used as an alternative way of setting the page title. However, `nuxt.config` does not allow the page title to be dynamic. Therefore, it is recommended to use `titleTemplate` in the `app.vue` file to add a dynamic title, which is then applied to all routes of your Nuxt app.
|
||||
|
||||
### Add External CSS
|
||||
|
||||
The example below inserts Google Fonts using the `link` property of the `useHead` composable:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
useHead({
|
||||
link: [
|
||||
{
|
||||
rel: 'preconnect',
|
||||
href: 'https://fonts.googleapis.com'
|
||||
},
|
||||
{
|
||||
rel: 'stylesheet',
|
||||
href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
|
||||
crossorigin: ''
|
||||
}
|
||||
]
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
### Add Third-party Script
|
||||
|
||||
The example below inserts a third-party script using the `script` property of the `useHead` composable:
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
useHead({
|
||||
script: [
|
||||
{
|
||||
src: 'https://third-party-script.com',
|
||||
body: true
|
||||
}
|
||||
]
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
You can use the `body: true` option to add the above script at the end of the `<body>` tag.
|
||||
|
||||
:ReadMore{link="/guide/features/head-management"}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user