dom:beforeRender Hook · Unhead [Unhead Home](https://unhead.unjs.io/ "Home") - [Docs](https://unhead.unjs.io/docs/typescript/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/typescript/head/guides/get-started/overview) [API](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview) [Releases](https://unhead.unjs.io/docs/typescript/releases/v3) TypeScript - [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/head/api/hooks/dom-before-render) - [Switch to Vue](https://unhead.unjs.io/docs/vue/head/api/hooks/dom-before-render) - [Switch to React](https://unhead.unjs.io/docs/react/head/api/hooks/dom-before-render) - [Switch to Svelte](https://unhead.unjs.io/docs/svelte/head/api/hooks/dom-before-render) - [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/head/api/hooks/dom-before-render) - [Switch to Angular](https://unhead.unjs.io/docs/angular/head/api/hooks/dom-before-render) - [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/head/api/hooks/dom-before-render) v3 (stable) Head - [Discord Support](https://discord.com/invite/275MBUBvgP) - [TypeScript Playground](https://stackblitz.com/edit/github-hhxywsb5) - Get Started - [Overview](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview) - Composables - [`useHead()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head) - [`useHeadSafe()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe) - [`useSeoMeta()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta) - [`useScript()`](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script) - Hooks - [entries:updated](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-updated) - [entries:resolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-resolve) - [entries:normalize](https://unhead.unjs.io/docs/typescript/head/api/hooks/entries-normalize) - [tag:normalise](https://unhead.unjs.io/docs/typescript/head/api/hooks/tag-normalise) - [tags:beforeResolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-before-resolve) - [tags:resolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-resolve) - [tags:afterResolve](https://unhead.unjs.io/docs/typescript/head/api/hooks/tags-after-resolve) - [dom:beforeRender](https://unhead.unjs.io/docs/typescript/head/api/hooks/dom-before-render) - [ssr:beforeRender](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-before-render) - [ssr:render](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-render) - [ssr:rendered](https://unhead.unjs.io/docs/typescript/head/api/hooks/ssr-rendered) - [script:updated](https://unhead.unjs.io/docs/typescript/head/api/hooks/script-updated) - [Plugins](https://unhead.unjs.io/docs/head/api/plugins) Hooks # dom:beforeRender Hook [Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/09.dom-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 `dom:beforeRender` hook is called before tags are rendered to the DOM in client-side environments. This hook allows you to control whether rendering should proceed and provides access to rendering context. ## [Hook Signature](#hook-signature) ``` export interface Hook { 'dom:beforeRender': (ctx: DomBeforeRenderCtx) => SyncHookResult } ``` ### [Parameters](#parameters) | Name | Type | Description | | --- | --- | --- | | `ctx` | `DomBeforeRenderCtx` | Context object with rendering information | The `DomBeforeRenderCtx` interface extends `ShouldRenderContext`: ``` interface DomBeforeRenderCtx extends ShouldRenderContext { tags: HeadTag[] } 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' const head = createHead({ hooks: { 'dom:beforeRender': (ctx) => { // Log rendering intent console.log('About to render tags to DOM') // You can prevent rendering by setting shouldRender to false if (window.document.querySelector('meta[name="unhead-rendered"]')) { console.log('Preventing re-render as tags are already rendered') ctx.shouldRender = false } } } }) ``` ## [Use Cases](#use-cases) ### [Conditional Rendering](#conditional-rendering) Control whether rendering should proceed based on page conditions: ``` import { defineHeadPlugin } from 'unhead' export const conditionalRenderPlugin = defineHeadPlugin({ hooks: { 'dom:beforeRender': (ctx) => { // Only render head tags if we're not in a specific context if (window.location.pathname.startsWith('/admin')) { // For admin pages, we want to prevent automatic rendering // because we'll handle it differently ctx.shouldRender = false } // Prevent rendering during specific user interactions if (document.body.classList.contains('modal-open')) { // Don't update head while modal is open to prevent flickering ctx.shouldRender = false } } } }) ``` ### [Render Preparation](#render-preparation) Prepare the DOM environment before rendering: ``` import { defineHeadPlugin } from 'unhead' export const renderPreparationPlugin = defineHeadPlugin({ hooks: { 'dom:beforeRender': () => { // Add rendering flag to prevent duplicate processing if (!document.querySelector('meta[name="unhead-render-id"]')) { const meta = document.createElement('meta') meta.setAttribute('name', 'unhead-render-id') meta.setAttribute('content', Date.now().toString()) document.head.appendChild(meta) } // Clean up specific tags that we always want to manage ourselves const existingCanonical = document.querySelector('link[rel="canonical"]') if (existingCanonical) { existingCanonical.remove() } } } }) ``` ### [Delayed Rendering](#delayed-rendering) Set up delayed rendering for better performance: ``` import { defineHeadPlugin } from 'unhead' export const delayedRenderPlugin = defineHeadPlugin({ hooks: { 'dom:beforeRender': (ctx) => { // Check if this is the initial page load const isInitialLoad = !document.querySelector('[data-unhead-rendered]') if (isInitialLoad) { // For initial load, we can delay non-critical head updates // until the page has finished loading if (document.readyState !== 'complete') { // Delay rendering until page is complete ctx.shouldRender = false // Set up listener to trigger rendering when ready window.addEventListener('load', () => { // Force head to re-evaluate rendering setTimeout(() => { head.hooks.callHook('entries:updated', head) }, 0) }, { once: true }) } } } } }) ``` [Edit this page](https://github.com/unjs/unhead/edit/main/docs/head/7.api/hooks/09.dom-before-render.md) [Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/head/7.api/hooks/09.dom-before-render.md) Did this page help you? [tags:afterResolve Final hook before rendering. Perform security checks, reorder tags for performance, and process content before output.](https://unhead.unjs.io/docs/head/api/hooks/tags-after-resolve) [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) 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/typescript/head/guides/get-started/overview) - [useHead](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head) - [useSeoMeta](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta) - [useHeadSafe](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe) - [useScript](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script) ### Schema.org - [Getting Started](https://unhead.unjs.io/docs/typescript/schema-org/guides/get-started/overview) - [useSchemaOrg](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org) - [Nodes](https://unhead.unjs.io/docs/typescript/schema-org/guides/core-concepts/nodes) - [Recipes](https://unhead.unjs.io/docs/typescript/schema-org/guides/recipes/identity) ### Guides - [Titles](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles) - [Streaming SSR](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming) - [DOM Events](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling) - [Plugins](https://unhead.unjs.io/docs/typescript/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 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)