Skip to content
This repository was archived by the owner on Apr 6, 2023. It is now read-only.

docs: add documentation for titleTemplate #5057

Closed
entity wants to merge 6 commits into from
Closed

docs: add documentation for titleTemplate #5057

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4663a2f
Added explainer for `titleTemplate`.
entity May 19, 2022
5170d33
Update docs/content/2.guide/2.features/4.head-management.md
entity May 19, 2022
4121af7
Update docs/content/2.guide/2.features/4.head-management.md
entity May 19, 2022
b616cdc
Update docs/content/2.guide/2.features/4.head-management.md
entity May 19, 2022
071c14e
Updated wording for title template
entity May 19, 2022
b746828
Fix linting issue
entity May 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 29 additions & 3 deletions docs/content/2.guide/2.features/4.head-management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,7 @@ For example:
```vue
<script setup>
useHead({
titleTemplate: 'My App - %s',
// or, instead:
// titleTemplate: (title) => `My App - ${title}`,
title: 'My App',
viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
charset: 'utf-8',
meta: [
Expand All @@ -31,6 +29,34 @@ useHead({
::ReadMore{link="/api/composables/use-head"}
::

## Title Templates

You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site, for example, by adding the name of your site to the title of every page.

Create a `title.js` plugin within your `plugins` folder, with the following code:
Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Create a `title.js` plugin within your `plugins` folder, with the following code:
The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function. If you want to use a function (for full control), then this cannot be set in your `nuxt.config`, and it is recommended instead to set it within your `app.vue` file, where it will apply to all pages on your site:


```js
export default defineNuxtPlugin(() => {
useHead({
titleTemplate: (titleChunk) => {
return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
},
});
});
```

Then you can set a title as you usually would:
Comment on lines +38 to +48
Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```js
export default defineNuxtPlugin(() => {
useHead({
titleTemplate: (titleChunk) => {
return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
},
});
});
```
Then you can set a title as you usually would:


```vue [/pages/my-page.vue]
<script setup>
useHead({
title: 'My Page'
Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: 'My Page'
titleTemplate: (titleChunk) => {
return titleChunk ? `${titleChunk} - Site Title` : 'Site Title';
},

Copy link
Copy Markdown
Contributor Author

@entity entity May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought we needed a plugin for it to work? As the current function approach does nothing.

Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the function approach should work everywhere but in nuxt.config. If not, it's a bug and I'll fix it.

Copy link
Copy Markdown
Contributor Author

@entity entity May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even with the following example in app.vue:

<script setup>
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - Site` : 'Site: Default Text';
  },
});
</script>

<template>
  <div>
    <NuxtLayout>
      <NuxtPage/>
    </NuxtLayout>
  </div>
</template>

If you don't pass a useHead to your page, it won't default it.

Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's a separate issue.

Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR to fix it: #5064

});
</script>
```

This will now appear as 'My Page - Site Title' in the browser tab. You can also pass `null` to default to the site title.
Copy link
Copy Markdown
Member

@danielroe danielroe May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This will now appear as 'My Page - Site Title' in the browser tab. You can also pass `null` to default to the site title.
Now, if you set the title to `My Page` with `useHead` on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You can also pass `null` to default to the site title.


## Meta Components

Nuxt provides `<Title>`, `<Base>`, `<Script>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>` components so that you can interact directly with your metadata within your component's template.
Expand Down