ssr:beforeRender Hook · Unhead

[Unhead Home](https://unhead.unjs.io/ "Home")

- [Docs](https://unhead.unjs.io/docs/vue/head/guides/get-started/overview)
- [Tools](https://unhead.unjs.io/tools)
- [Learn](https://unhead.unjs.io/learn/guides/what-is-capo)

[Releases](https://unhead.unjs.io/releases)

Search…```k`` /`

[Unhead on GitHub](https://github.com/unjs/unhead)

[User Guides](https://unhead.unjs.io/docs/vue/head/guides/get-started/overview)

[API](https://unhead.unjs.io/docs/vue/head/api/get-started/overview)

[Releases](https://unhead.unjs.io/docs/vue/releases/v3)

Vue

- [Switch to Vue](https://unhead.unjs.io/docs/vue/head/api/hooks/ssr-before-render)
- [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-before-render)
- [Switch to React](https://unhead.unjs.io/docs/react/head/api/hooks/ssr-before-render)
- [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/api/hooks/ssr-before-render)
- [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/api/hooks/ssr-before-render)
- [Switch to Angular](https://unhead.unjs.io/docs/angular/head/api/hooks/ssr-before-render)
- [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/api/hooks/ssr-before-render)

v3 (stable)

Head

- [Discord Support](https://discord.com/invite/275MBUBvgP)
- [Vue Playground](https://stackblitz.com/edit/github-1ftqrmwn)

- Get Started
  - [Overview](https://unhead.unjs.io/docs/vue/head/api/get-started/overview)
- Composables
  - [`useHead()`](https://unhead.unjs.io/docs/vue/head/api/composables/use-head)
  - [`useHeadSafe()`](https://unhead.unjs.io/docs/vue/head/api/composables/use-head-safe)
  - [`useSeoMeta()`](https://unhead.unjs.io/docs/vue/head/api/composables/use-seo-meta)
  - [`useScript()`](https://unhead.unjs.io/docs/vue/head/api/composables/use-script)
- Hooks
  - [entries:updated](https://unhead.unjs.io/docs/vue/head/api/hooks/entries-updated)
  - [entries:resolve](https://unhead.unjs.io/docs/vue/head/api/hooks/entries-resolve)
  - [entries:normalize](https://unhead.unjs.io/docs/vue/head/api/hooks/entries-normalize)
  - [tag:normalise](https://unhead.unjs.io/docs/vue/head/api/hooks/tag-normalise)
  - [tags:beforeResolve](https://unhead.unjs.io/docs/vue/head/api/hooks/tags-before-resolve)
  - [tags:resolve](https://unhead.unjs.io/docs/vue/head/api/hooks/tags-resolve)
  - [tags:afterResolve](https://unhead.unjs.io/docs/vue/head/api/hooks/tags-after-resolve)
  - [dom:beforeRender](https://unhead.unjs.io/docs/vue/head/api/hooks/dom-before-render)
  - [ssr:beforeRender](https://unhead.unjs.io/docs/vue/head/api/hooks/ssr-before-render)
  - [ssr:render](https://unhead.unjs.io/docs/vue/head/api/hooks/ssr-render)
  - [ssr:rendered](https://unhead.unjs.io/docs/vue/head/api/hooks/ssr-rendered)
  - [script:updated](https://unhead.unjs.io/docs/vue/head/api/hooks/script-updated)
- [Plugins](https://unhead.unjs.io/docs/head/api/plugins)

Hooks

# ssr:beforeRender Hook

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/12.ssr-before-render.md)

Last updated Jan 19, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: sync](https://github.com/unjs/unhead/commit/d2f86454774aa60706628b46a850653e1e4d56d9).

On this page

- [Hook Signature](#hook-signature)
- [Usage Example](#usage-example)
- [Use Cases](#use-cases)

The `ssr:beforeRender` hook is called before the server-side rendering process begins. This hook allows you to control whether the SSR rendering should proceed and is a good place to perform any initialization or checks specific to the server environment.

## [Hook Signature](#hook-signature)

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

### [Parameters](#parameters)

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `ShouldRenderContext` | Context object with rendering control |

The `ShouldRenderContext` interface is defined as:

```
interface ShouldRenderContext {
  shouldRender: boolean
}
```

### [Returns](#returns)

`SyncHookResult` which is `void`. This hook is synchronous and cannot be async.

## [Usage Example](#usage-example)

```
import { createHead } from '@unhead/vue'

const head = createHead({
  hooks: {
    'ssr:beforeRender': (ctx) => {
      // Log SSR rendering intent
      console.log('Preparing for server-side rendering of head tags')

      // You can prevent rendering by setting shouldRender to false
      if (process.env.SKIP_HEAD_RENDERING === 'true') {
        console.log('Skipping head tag rendering based on environment setting')
        ctx.shouldRender = false
      }
    }
  }
})
```

## [Use Cases](#use-cases)

### [Conditional SSR Rendering](#conditional-ssr-rendering)

Control whether SSR rendering should proceed based on server conditions:

```
import { defineHeadPlugin } from '@unhead/vue'

export const conditionalSsrPlugin = defineHeadPlugin({
  hooks: {
    'ssr:beforeRender': (ctx) => {
      // Only render head tags for specific routes or conditions
      const currentRoute = getCurrentRoute() // Your route detection logic

      // Skip head rendering for specific routes (e.g., API endpoints)
      if (currentRoute.startsWith('/api/')) {
        ctx.shouldRender = false
      }

      // Skip head rendering for certain user agents
      const userAgent = getUserAgent() // Your user-agent detection logic
      if (userAgent.includes('Googlebot') || userAgent.includes('crawler')) {
        // For bots, we might use a different rendering strategy
        ctx.shouldRender = false
      }
    }
  }
})
```

### [SSR Environment Setup](#ssr-environment-setup)

Set up the server environment before rendering:

```
import { defineHeadPlugin } from '@unhead/vue'

export const ssrEnvironmentPlugin = defineHeadPlugin({
  hooks: {
    'ssr:beforeRender': () => {
      // Set up globalThis variables or state needed for SSR
      globalThis.__UNHEAD_SSR_ENABLED = true

      // Configure environment-specific settings
      if (process.env.NODE_ENV === 'development') {
        // In development, we might want to add debug information
        globalThis.__UNHEAD_DEBUG = true
      }

      // Prepare rendering context
      globalThis.__UNHEAD_RENDER_CONTEXT = {
        startTime: process.hrtime(),
        renderer: 'node',
        version: process.version
      }
    }
  }
})
```

### [Performance Optimization](#performance-optimization)

Skip unnecessary rendering for performance optimization:

```
import { defineHeadPlugin } from '@unhead/vue'

export const ssrPerformancePlugin = defineHeadPlugin({
  hooks: {
    'ssr:beforeRender': (ctx) => {
      // Cache key based on current request
      const cacheKey = generateCacheKey() // Your cache key generation logic

      // Check if we have a cached version of the head HTML
      if (globalThis.__UNHEAD_CACHE && globalThis.__UNHEAD_CACHE[cacheKey]) {
        // Skip rendering and use cached value later
        ctx.shouldRender = false

        // Store cache key for later retrieval
        globalThis.__UNHEAD_CURRENT_CACHE_KEY = cacheKey

        console.log('Using cached head HTML, skipping rendering')
      }
      else {
        // Prepare to render and cache
        globalThis.__UNHEAD_CURRENT_CACHE_KEY = cacheKey
      }
    }
  }
})
```

[Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/7.api/hooks/12.ssr-before-render.md)

[Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/12.ssr-before-render.md)

Did this page help you?

[dom:beforeRender Hook called before DOM rendering. Control render timing, prepare the DOM environment, and conditionally prevent head tag updates.](https://unhead.unjs.io/docs/head/api/hooks/dom-before-render) [ssr:render Hook for SSR tag processing. Add server-specific tags, apply i18n, and optimize platform-specific rendering.](https://unhead.unjs.io/docs/head/api/hooks/ssr-render)

On this page

- [Hook Signature](#hook-signature)
- [Usage Example](#usage-example)
- [Use Cases](#use-cases)

[GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP)

[ /llms.txt](https://unhead.unjs.io/llms.txt)

[Part of the UnJS ecosystem](https://unjs.io/)

### Head Management

- [Getting Started](https://unhead.unjs.io/docs/vue/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/vue/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/vue/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/vue/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/vue/head/api/composables/use-script)

### Schema.org

- [Getting Started](https://unhead.unjs.io/docs/vue/schema-org/guides/get-started/overview)
- [useSchemaOrg](https://unhead.unjs.io/docs/vue/schema-org/api/composables/use-schema-org)
- [Nodes](https://unhead.unjs.io/docs/vue/schema-org/guides/core-concepts/nodes)
- [Recipes](https://unhead.unjs.io/docs/vue/schema-org/guides/recipes/identity)

### Guides

- [Titles](https://unhead.unjs.io/docs/vue/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/vue/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/vue/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/vue/head/guides/plugins/template-params)

### Tools

- [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator)
- [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator)
- [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator)
- [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer)

### Articles

- [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo)

### Research

- [State of <head> in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026)
- [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance)
- [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research)

Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)