diff --git a/docs/content/1.get-started/5.watch-outs.md b/docs/content/1.get-started/5.watch-outs.md index 5ff6fb35..517456e7 100644 --- a/docs/content/1.get-started/5.watch-outs.md +++ b/docs/content/1.get-started/5.watch-outs.md @@ -53,8 +53,8 @@ Read about the [Ionic Vue lifecycle hooks here](https://ionicframework.com/docs/ Because of this, some expected functionality from Nuxt or other modules may not work or may require changes to get functioning: ::list{type="warning"} -- **The composable `useHead()` will not work out of the box**. - See [our cookbook page](/cookbook/page-metadata) for how to continue using `useHead()` +- **Use the module's auto-imported `useHead()` composable**. + It accounts for Ionic's page lifecycle. See [our cookbook page](/cookbook/page-metadata) for usage details. - **Certain Vue Router components should not be used**. This includes ``, ``, and `` - [read more here](https://ionicframework.com/docs/vue/lifecycle#how-ionic-framework-handles-the-life-of-a-page). :: diff --git a/docs/content/3.cookbook/4.page-metadata.md b/docs/content/3.cookbook/4.page-metadata.md index 7c6b9e44..cf1aa5ab 100644 --- a/docs/content/3.cookbook/4.page-metadata.md +++ b/docs/content/3.cookbook/4.page-metadata.md @@ -1,14 +1,52 @@ --- title: useHead / Page Meta -description: "" +description: Manage page titles and head tags with the Ionic-compatible useHead composable. --- +The module auto-imports an Ionic-compatible implementation of Nuxt's `useHead` composable. Ionic keeps inactive pages mounted, so Vue's unmount hooks cannot reliably remove their head entries. + +Inside a component, the composable associates each head entry with the current route. It disposes the route's entries on `onIonViewDidLeave` and restores them on `onIonViewDidEnter`. + +## Usage + +Use it like the standard Nuxt composable: + +```vue [pages/products/[id].vue] + +``` + ::callout{color="warning" icon="i-lucide-alert-triangle"} -⚠️ This page is a stub and needs further information. +Importing `useHead` directly from `@unhead/vue` bypasses the Ionic lifecycle handling. :: -The composable `useHead()` will not work out of the box. +## Usage outside components + +Since [nuxt-modules/ionic#825](https://github.com/nuxt-modules/ionic/pull/825), `useHead` also works without an active component instance. This is required by Nuxt plugins and modules such as `@nuxtjs/i18n`. + +```ts [plugins/app-head.ts] +export default defineNuxtPlugin(() => { + useHead({ + titleTemplate: title => title ? `${title} · My App` : 'My App', + }) +}) +``` -Please see this issue for reference: https://github.com/nuxt-modules/ionic/issues/6 +Without a component instance, the composable skips `useRoute`, `useRouter`, and the component lifecycle hooks. The head entry is registered directly and remains active until it is patched or disposed. -Also see the documentation for use-head: https://nuxt.com/docs/api/composables/use-head +The composable returns an entry with `patch()` and `dispose()` methods, matching the standard `useHead` API. + +::callout{color="info" icon="i-lucide-info"} +See the [Nuxt `useHead` documentation](https://nuxt.com/docs/api/composables/use-head) for supported properties and reactive inputs. +::