ssr:render Hook · Unhead

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

- [Docs](https://unhead.unjs.io/docs/svelte/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/svelte/head/guides/get-started/overview)

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

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

Svelte

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

v3 (stable)

Head

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

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

Hooks

# ssr:render Hook

[Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/13.ssr-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:render` hook is called during the server-side rendering process after tags have been resolved but before they're converted to HTML strings. This hook provides access to the finalized tags and allows for last-minute modifications specific to server-side rendering.

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

```
export interface Hook {
  'ssr:render': (ctx: { tags: HeadTag[] }) => SyncHookResult
}
```

### [Parameters](#parameters)

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | Object | Context object with rendering information |
| `ctx.tags` | `HeadTag[]` | Array of finalized head tags being rendered |

### [Returns](#returns)

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

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

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

const head = createHead({
  hooks: {
    'ssr:render': (ctx) => {
      // Log the tags being rendered in SSR
      console.log(\`Rendering ${ctx.tags.length} tags during SSR\`)

      // Add a server-specific meta tag
      ctx.tags.push({
        tag: 'meta',
        props: {
          name: 'ssr-timestamp',
          content: Date.now().toString()
        }
      })
    }
  }
})
```

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

### [Server-specific Tag Modifications](#server-specific-tag-modifications)

Modify tags specifically for server-side rendering:

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

export const ssrTagsPlugin = defineHeadPlugin({
  hooks: {
    'ssr:render': (ctx) => {
      // Add SSR-specific attributes to all tags
      ctx.tags.forEach((tag) => {
        if (tag.props) {
          // Add data attribute to indicate this was rendered on the server
          tag.props['data-ssr'] = 'true'
        }
      })

      // Add server-rendered timestamp
      ctx.tags.push({
        tag: 'meta',
        props: {
          name: 'server-render-time',
          content: new Date().toISOString()
        }
      })

      // Add cache-control meta tag for browsers
      ctx.tags.push({
        tag: 'meta',
        props: {
          'http-equiv': 'Cache-Control',
          'content': 'no-cache, no-store, must-revalidate'
        }
      })
    }
  }
})
```

### [Platform-specific Optimizations](#platform-specific-optimizations)

Apply optimizations based on the server platform:

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

export const platformOptimizationPlugin = defineHeadPlugin({
  hooks: {
    'ssr:render': (ctx) => {
      // Add preload hints based on platform capabilities
      const isNodeJS = typeof process !== 'undefined' && process.versions && process.versions.node

      if (isNodeJS) {
        // Modern Node.js - add HTTP/2 Server Push hints through special meta tags
        const criticalResources = [
          { path: '/css/main.css', as: 'style' },
          { path: '/js/main.js', as: 'script' }
        ]

        criticalResources.forEach((resource) => {
          ctx.tags.push({
            tag: 'link',
            props: {
              rel: 'preload',
              href: resource.path,
              as: resource.as,
              crossorigin: resource.as === 'font' ? 'anonymous' : undefined
            }
          })
        })
      }

      // Remove client-only script tags during SSR
      ctx.tags = ctx.tags.filter((tag) => {
        if (tag.tag === 'script' && tag.props.type === 'application/json') {
          // Keep JSON data scripts for hydration
          return true
        }
        if (tag.tag === 'script' && tag.props['data-client-only']) {
          // Remove client-only scripts during SSR
          return false
        }
        return true
      })
    }
  }
})
```

### [Internationalization Support](#internationalization-support)

Handle internationalization (i18n) aspects in server rendering:

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

export const i18nSsrPlugin = defineHeadPlugin({
  hooks: {
    'ssr:render': (ctx) => {
      // Get current locale from your i18n system
      const currentLocale = getCurrentLocale() // Your locale detection logic
      const defaultLocale = getDefaultLocale()

      // Find existing language tags
      const htmlLangTag = ctx.tags.find(tag =>
        tag.tag === 'htmlAttrs' && tag.props.lang
      )

      // Update or add language attributes
      if (htmlLangTag) {
        htmlLangTag.props.lang = currentLocale
      }
      else {
        // Add lang attribute to html tag
        ctx.tags.push({
          tag: 'htmlAttrs',
          props: { lang: currentLocale }
        })
      }

      // Add language alternates for SEO
      const supportedLocales = getSupportedLocales() // Your locales list
      const currentPath = getCurrentPath() // Current request path

      supportedLocales.forEach((locale) => {
        // Generate localized URL
        const localizedUrl = generateLocalizedUrl(currentPath, locale)

        // Add hreflang link
        ctx.tags.push({
          tag: 'link',
          props: {
            rel: 'alternate',
            hreflang: locale,
            href: localizedUrl
          }
        })
      })

      // Add x-default hreflang
      ctx.tags.push({
        tag: 'link',
        props: {
          rel: 'alternate',
          hreflang: 'x-default',
          href: generateLocalizedUrl(currentPath, defaultLocale)
        }
      })
    }
  }
})
```

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

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

Did this page help you?

[ssr:beforeRender Hook called before SSR rendering. Control server rendering, set up environment, and optimize performance with caching strategies.](https://unhead.unjs.io/docs/head/api/hooks/ssr-before-render) [ssr:rendered Hook called after SSR completes. Post-process HTML output, implement caching, and collect rendering metrics.](https://unhead.unjs.io/docs/head/api/hooks/ssr-rendered)

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/svelte/head/guides/get-started/overview)
- [useHead](https://unhead.unjs.io/docs/svelte/head/api/composables/use-head)
- [useSeoMeta](https://unhead.unjs.io/docs/svelte/head/api/composables/use-seo-meta)
- [useHeadSafe](https://unhead.unjs.io/docs/svelte/head/api/composables/use-head-safe)
- [useScript](https://unhead.unjs.io/docs/svelte/head/api/composables/use-script)

### Schema.org

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

### Guides

- [Titles](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/titles)
- [Streaming SSR](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/streaming)
- [DOM Events](https://unhead.unjs.io/docs/svelte/head/guides/core-concepts/dom-event-handling)
- [Plugins](https://unhead.unjs.io/docs/svelte/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)