feat: access resolved head with onRendered (#712)

harlan-zw · claude · web-flow · commit 55166ee65f8f · 2026-04-06T01:51:43.000+10:00
* feat(unhead): add `onRendered` option to `HeadEntryOptions` Adds a client-side callback option to useHead/useSeoMeta/useHeadSafe that fires after DOM updates are applied. This enables synchronizing external tools (e.g. analytics) with the current document head state. The callback is automatically cleaned up when the entry is disposed (including on component unmount). Ignored during SSR. Resolves #615 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix: register onRendered hook in client head, not core The client createHead wraps core push() with its own push(), and hooks are only available on the client wrapper. Moved hook registration to the client head's push() where hooks are accessible. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(unhead): register onRendered hook before triggering entries:updated The onRendered hook was registered after entries:updated was called, but entries:updated synchronously triggers the renderer which fires dom:rendered. This meant the callback was never invoked on the initial render. Also fixes multi-entry test expectations to account for each push() triggering an immediate render, and adds a Vue component unmount test to verify onRendered cleanup on component lifecycle. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(vue,solid): preserve component scope for onRendered callbacks Wrap onRendered callbacks to run within the registering component's scope context. This ensures reactive tracking works correctly and provides an extra safety layer — disposed scopes silently no-op. - Vue: capture getCurrentScope(), run callback via scope.run() - Solid: capture getOwner(), run callback via runWithOwner() - React/Svelte/Angular: no scope concept — closures + disposal cleanup already handle this correctly Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/docs/0.angular/head/guides/0.get-started/2.migration.md b/docs/0.angular/head/guides/0.get-started/2.migration.md
@@ -99,7 +99,7 @@ if (isPlatformBrowser(this.platformId)) {
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/0.nuxt/head/guides/0.get-started/1.migration.md b/docs/0.nuxt/head/guides/0.get-started/1.migration.md
@@ -96,7 +96,7 @@ if (import.meta.server) {
 If you're using Unhead hooks directly:
 - `init` hook removed
 - `dom:renderTag` hook removed
-- `dom:rendered` hook removed
+- `dom:rendered` hook removed - use the `onRendered` option on `useHead()` instead
 - `dom:beforeRender` is now synchronous
 - `renderDOMHead` is now synchronous
 
diff --git a/docs/0.react/head/guides/0.get-started/2.migration.md b/docs/0.react/head/guides/0.get-started/2.migration.md
@@ -97,7 +97,7 @@ if (typeof window !== 'undefined') {
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/0.solid-js/head/guides/0.get-started/2.migration.md b/docs/0.solid-js/head/guides/0.get-started/2.migration.md
@@ -99,7 +99,7 @@ if (!isServer) {
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/0.svelte/head/guides/0.get-started/2.migration.md b/docs/0.svelte/head/guides/0.get-started/2.migration.md
@@ -99,7 +99,7 @@ if (browser) {
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/0.typescript/head/guides/0.get-started/1.migration.md b/docs/0.typescript/head/guides/0.get-started/1.migration.md
@@ -133,7 +133,7 @@ head.push({
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/0.vue/head/guides/0.get-started/1.migration.md b/docs/0.vue/head/guides/0.get-started/1.migration.md
@@ -149,7 +149,7 @@ useHead({
 The following hooks have been removed:
 - `init` - No longer needed
 - `dom:renderTag` - DOM rendering is now synchronous
-- `dom:rendered` - Use code after `renderDOMHead()` instead
+- `dom:rendered` - Use the `onRendered` option on `useHead()` instead
 
 The `dom:beforeRender` hook is now synchronous and `renderDOMHead` no longer returns a Promise:
 
diff --git a/docs/head/7.api/composables/0.use-head.md b/docs/head/7.api/composables/0.use-head.md
@@ -148,6 +148,9 @@ export interface HeadEntryOptions {
   // Where to position tags in the document
   tagPosition?: 'head' | 'bodyClose' | 'bodyOpen'
 
+  // Callback fired after DOM updates are applied (client-only, ignored during SSR)
+  onRendered?: (ctx: { renders: DomRenderTagContext[] }) => void | Promise<void>
+
   // Custom head instance
   head?: Unhead
 }
@@ -177,6 +180,32 @@ useHead({
 The `tagPriority`{lang="ts"} option is particularly useful for controlling render order when you have multiple head entries that might contain similar tags.
 ::
 
+## Synchronizing with DOM Updates
+
+The `onRendered` option lets you run a callback after unhead has finished applying DOM updates.
+This is useful for synchronising external tools like analytics with the current document head (e.g. reading `document.title`
+after it has been set).
+
+```ts
+import { useHead } from '@unhead/dynamic-import'
+
+useHead({
+  title: 'My Page',
+}, {
+  onRendered({ renders }) {
+    // document.title is guaranteed to be up-to-date here
+    analytics.track('Page View', { title: document.title })
+  }
+})
+```
+
+- The callback fires on **every** DOM render, not just the first.
+- It is **ignored during SSR** — only runs on the client.
+- The callback is automatically cleaned up when the entry is disposed (including on component unmount in frameworks).
+- The `renders` array contains the render context for each tag that was processed.
+
+Works with all composables that accept `HeadEntryOptions` — `useHead()`, `useSeoMeta()`, and `useHeadSafe()`.
+
 ## Reactivity
 
 ::VueOnly
diff --git a/packages/solid-js/src/composables.ts b/packages/solid-js/src/composables.ts
@@ -9,7 +9,7 @@ import type {
   UseScriptReturn,
   UseSeoMetaInput,
 } from 'unhead/types'
-import { createEffect, createSignal, onCleanup, onMount, useContext } from 'solid-js'
+import { createEffect, createSignal, getOwner, onCleanup, onMount, runWithOwner, useContext } from 'solid-js'
 import { isServer } from 'solid-js/web'
 import { useHead as baseHead, useHeadSafe as baseHeadSafe, useSeoMeta as baseSeoMeta, useScript as baseUseScript } from 'unhead'
 import { UnheadContext } from './context'
@@ -25,6 +25,14 @@ export function useUnhead(): Unhead {
 
 function withSideEffects<T extends ActiveHeadEntry<any>>(input: any, options: any, fn: any): T {
   const unhead = options.head || useUnhead()
+  // Wrap onRendered to preserve the Solid reactive owner context
+  if (options.onRendered && !isServer) {
+    const owner = getOwner()
+    if (owner) {
+      const _onRendered = options.onRendered
+      options = { ...options, onRendered: (ctx: any) => runWithOwner(owner, () => _onRendered(ctx)) }
+    }
+  }
   const entry = fn(unhead, input, options) as T
   // On client, set up reactive updates and cleanup
   if (!isServer) {
diff --git a/packages/unhead/src/client/createHead.ts b/packages/unhead/src/client/createHead.ts
@@ -34,6 +34,10 @@ export function createHead<T = ResolvableHead>(options: CreateClientHeadOptions
       hooks.callHook('entries:updated', head)
     },
     push(input: T, _options?: HeadEntryOptions) {
+      const onRendered = _options?.onRendered
+      const unhook = onRendered
+        ? hooks.hook('dom:rendered', onRendered as any)
+        : undefined
       const active = core.push(input, _options)
       core.entries.get(active._i)!._o = input
       dirty = true
@@ -46,6 +50,7 @@ export function createHead<T = ResolvableHead>(options: CreateClientHeadOptions
           hooks.callHook('entries:updated', head)
         },
         dispose() {
+          unhook?.()
           if (core.entries.has(active._i)) {
             active.dispose()
             head.invalidate()
diff --git a/packages/unhead/src/types/head.ts b/packages/unhead/src/types/head.ts
@@ -1,5 +1,5 @@
 import type { HookableCore } from 'hookable'
-import type { ClientHeadHooks, HeadHooks, ServerHeadHooks } from './hooks'
+import type { ClientHeadHooks, DomRenderTagContext, HeadHooks, ServerHeadHooks } from './hooks'
 import type { ResolvableHead } from './schema'
 import type { HeadTag, ProcessesTemplateParams, ResolvesDuplicates, TagPosition, TagPriority, TemplateParams } from './tags'
 
@@ -156,6 +156,21 @@ export interface CreateClientHeadOptions extends CreateHeadOptions {
 
 export interface HeadEntryOptions extends TagPosition, TagPriority, ProcessesTemplateParams, ResolvesDuplicates {
   head?: Unhead
+  /**
+   * Called after unhead has finished applying DOM updates.
+   *
+   * Useful for synchronising external tools (e.g. analytics) with the current document head.
+   *
+   * Only called on the client — ignored during SSR.
+   *
+   * @example
+   * useHead({ title: 'My Page' }, {
+   *   onRendered({ renders }) {
+   *     amplitude.track('Page View', { title: document.title })
+   *   }
+   * })
+   */
+  onRendered?: (ctx: { renders: DomRenderTagContext[] }) => void | Promise<void>
   /**
    * @internal
    */
diff --git a/packages/unhead/src/unhead.ts b/packages/unhead/src/unhead.ts
@@ -27,6 +27,7 @@ export function createUnhead<T = ResolvableHead, R = unknown>(renderer: HeadRend
       const _i = _options?._index ?? head._entryCount++
       const options = _options ? { ..._options } : {}
       delete (options as any).head
+      delete (options as any).onRendered
       const entry: HeadEntry<T> = { _i, input, options }
       entries.set(_i, entry)
       const active: ActiveHeadEntry<T> = {
diff --git a/packages/unhead/test/unit/client/onRendered.test.ts b/packages/unhead/test/unit/client/onRendered.test.ts
@@ -0,0 +1,112 @@
+import { renderDOMHead } from '@unhead/dom'
+import { describe, expect, it, vi } from 'vitest'
+import { useHead } from '../../../src'
+import { useDOMHead } from '../../util'
+
+describe('onRendered option', () => {
+  it('calls onRendered callback after DOM render', async () => {
+    const head = useDOMHead()
+    const onRendered = vi.fn()
+
+    useHead(head, { title: 'Hello World' }, { onRendered })
+
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+
+    expect(onRendered).toHaveBeenCalledOnce()
+  })
+
+  it('callback receives renders context with tags', async () => {
+    const head = useDOMHead()
+    let capturedCtx: any
+
+    useHead(head, { title: 'Test Page' }, {
+      onRendered(ctx) {
+        capturedCtx = ctx
+      },
+    })
+
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+
+    expect(capturedCtx).toBeDefined()
+    expect(capturedCtx.renders).toBeInstanceOf(Array)
+    const titleRender = capturedCtx.renders.find((r: any) => r.tag.tag === 'title')
+    expect(titleRender).toBeDefined()
+    expect(titleRender.tag.textContent).toBe('Test Page')
+  })
+
+  it('fires on every render', async () => {
+    const head = useDOMHead()
+    const onRendered = vi.fn()
+
+    useHead(head, { title: 'Initial' }, { onRendered })
+
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+    expect(onRendered).toHaveBeenCalledTimes(1)
+
+    head.push({ title: 'Updated' })
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+    expect(onRendered).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops firing after dispose', async () => {
+    const head = useDOMHead()
+    const onRendered = vi.fn()
+
+    const entry = useHead(head, { title: 'Page' }, { onRendered })
+
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+    expect(onRendered).toHaveBeenCalledTimes(1)
+
+    entry.dispose()
+
+    head.push({ title: 'Page 2' })
+    await renderDOMHead(head, { document: head.resolvedOptions.document! })
+    expect(onRendered).toHaveBeenCalledTimes(1)
+  })
+
+  it('is ignored during SSR', async () => {
+    const { createHead } = await import('../../../src/server')
+    const head = createHead({ disableDefaults: true })
+    const onRendered = vi.fn()
+
+    useHead(head, { title: 'SSR Page' }, { onRendered })
+
+    await head.render()
+    expect(onRendered).not.toHaveBeenCalled()
+  })
+
+  it('works with multiple entries each having onRendered', async () => {
+    const head = useDOMHead()
+    const onRendered1 = vi.fn()
+    const onRendered2 = vi.fn()
+
+    // First push triggers an immediate render (via entries:updated), onRendered1 fires
+    useHead(head, { title: 'Page' }, { onRendered: onRendered1 })
+    // Second push triggers another render, both onRendered1 and onRendered2 fire
+    useHead(head, { meta: [{ name: 'description', content: 'test' }] }, { onRendered: onRendered2 })
+
+    // onRendered fires on every render, not just renders from the owning entry
+    expect(onRendered1).toHaveBeenCalledTimes(2)
+    expect(onRendered2).toHaveBeenCalledOnce()
+  })
+
+  it('disposing one entry does not affect other onRendered callbacks', async () => {
+    const head = useDOMHead()
+    const onRendered1 = vi.fn()
+    const onRendered2 = vi.fn()
+
+    // First push: renders once, onRendered1 fires (1)
+    const entry1 = useHead(head, { title: 'Page' }, { onRendered: onRendered1 })
+    // Second push: renders again, both fire (onRendered1=2, onRendered2=1)
+    useHead(head, { meta: [{ name: 'description', content: 'test' }] }, { onRendered: onRendered2 })
+
+    expect(onRendered1).toHaveBeenCalledTimes(2)
+    expect(onRendered2).toHaveBeenCalledTimes(1)
+
+    entry1.dispose()
+
+    // dispose triggers invalidate which renders again, only onRendered2 fires
+    expect(onRendered1).toHaveBeenCalledTimes(2) // stopped
+    expect(onRendered2).toHaveBeenCalledTimes(2) // still fires
+  })
+})
diff --git a/packages/vue/src/composables.ts b/packages/vue/src/composables.ts
@@ -10,6 +10,7 @@ import { FlatMetaPlugin, SafeInputPlugin } from 'unhead/plugins'
 import { walkResolver } from 'unhead/utils'
 import {
   getCurrentInstance,
+  getCurrentScope,
   hasInjectionContext,
   inject,
   onActivated,
@@ -41,6 +42,15 @@ export function useHead<I = UseHeadInput>(input?: UseHeadInput, options: UseHead
 function clientUseHead<I = UseHeadInput>(head: Unhead<I>, input?: I, options: HeadEntryOptions = {}): ActiveHeadEntry<I> {
   const deactivated = ref(false)
 
+  // Wrap onRendered to preserve the Vue component's effect scope
+  if (options.onRendered) {
+    const scope = getCurrentScope()
+    if (scope) {
+      const _onRendered = options.onRendered
+      options = { ...options, onRendered: ctx => scope.run(() => _onRendered(ctx)) }
+    }
+  }
+
   let entry: ActiveHeadEntry<I>
   watchEffect(() => {
     const i = deactivated.value ? {} : walkResolver(input, VueResolver)
diff --git a/packages/vue/test/unit/dom/onRendered.test.ts b/packages/vue/test/unit/dom/onRendered.test.ts
