ssr:beforeRender Hook

The ssr:beforeRender hook runs at the start of head.render(), before Unhead resolves any tags. Set ctx.shouldRender to false to return an empty SSRHeadPayload and skip the remaining SSR hooks.

Hook Signature

export interface Hook {
  'ssr:beforeRender': (ctx: ShouldRenderContext) => HookResult
}

interface ShouldRenderContext {
  shouldRender: boolean
}

type HookResult = void | Promise<void>

Although the type permits a promise, the synchronous SSR renderer does not await hook results. Make changes to ctx synchronously.

Usage Example

import { defineHeadPlugin } from 'unhead/plugins'

export function conditionalSsrPlugin(shouldRenderHead: () => boolean) {
  return defineHeadPlugin({
    key: 'conditional-ssr',
    hooks: {
      'ssr:beforeRender': (ctx) => {
        ctx.shouldRender = shouldRenderHead()
      }
    }
  })
}

If you cache rendered head output, perform the cache lookup outside head.render(). Canceling this hook returns an empty payload; it does not substitute cached HTML.