fix: ensure inserting <title> in <head> updates document.title

serhalp · serhalp · commit 56b1fb37cacd · 2025-12-05T15:16:16.000-05:00
In #39306 we introduced a workaround that wraps the Gatsby Head API elements in an `<svg>` wrapper. React under the hood creates these children elements in the "SVG" namespace. In the case of `<title>`, this is problematic because when we insert it into the real `<head>`, browsers (as far as we can tell) do not trigger an update of `document.title` because this only occurs for `<title>` nodes in the HTML namespace. A node's namespace is immutable, even when using `cloneNode()` or `importNode()`. The only way to "reset" the namespace is to recreate a node.
diff --git a/e2e-tests/development-runtime/cypress/integration/functionality/queries-in-packages.js b/e2e-tests/development-runtime/cypress/integration/functionality/queries-in-packages.js
@@ -4,10 +4,8 @@ describe(`queries in packages`, () => {
   })
 
   it(`Should extract and run query from gatsby component`, () => {
-    // Note: in dev this may take a few ms to be populated due to the way the Gatsby Head API is
-    // implemented
-    cy.get("head > title").should(
-      `have.text`,
+    cy.title().should(
+      `eq`,
       `Testing queries in packages | Gatsby Default Starter`
     )
   })
diff --git a/e2e-tests/production-runtime/cypress/integration/head-function-export/head-with-wrap-root-element.js b/e2e-tests/production-runtime/cypress/integration/head-function-export/head-with-wrap-root-element.js
@@ -39,6 +39,14 @@ describe(`Head with wrapRootElement`, () => {
     cy.getTestElement(`jsonLD`).should(`have.text`, data.static.jsonLD)
   })
 
+  it(`updates document title`, () => {
+    cy.visit(
+      headFunctionExportSharedData.page.headWithWrapRooElement
+    ).waitForRouteChange()
+
+    cy.title().should(`eq`, contextValue.posts[0].title)
+  })
+
   it(`can use context values provided in wrapRootElement`, () => {
     cy.visit(
       headFunctionExportSharedData.page.headWithWrapRooElement
diff --git a/e2e-tests/production-runtime/cypress/integration/head-function-export/html-insertion.js b/e2e-tests/production-runtime/cypress/integration/head-function-export/html-insertion.js
@@ -14,10 +14,12 @@ Cypress.on("uncaught:exception", err => {
 describe(`Head function export html insertion`, () => {
   it(`should work with static data`, () => {
     cy.visit(page.basic).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.static.base)
     cy.getTestElement(`title`).should(`have.text`, data.static.title)
+    cy.title().should(`eq`, data.static.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.static.meta)
@@ -31,10 +33,12 @@ describe(`Head function export html insertion`, () => {
 
   it(`should work with data from a page query`, () => {
     cy.visit(page.pageQuery).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.queried.base)
     cy.getTestElement(`title`).should(`have.text`, data.queried.title)
+    cy.title().should(`eq`, data.queried.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.queried.meta)
@@ -47,10 +51,12 @@ describe(`Head function export html insertion`, () => {
 
   it(`should work when a Head function with static data is re-exported from the page`, () => {
     cy.visit(page.reExport).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.static.base)
     cy.getTestElement(`title`).should(`have.text`, data.static.title)
+    cy.title().should(`eq`, data.static.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.static.meta)
@@ -64,10 +70,12 @@ describe(`Head function export html insertion`, () => {
 
   it(`should work when an imported Head component with queried data is used`, () => {
     cy.visit(page.staticQuery).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.queried.base)
     cy.getTestElement(`title`).should(`have.text`, data.queried.title)
+    cy.title().should(`eq`, data.queried.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.queried.meta)
@@ -80,10 +88,12 @@ describe(`Head function export html insertion`, () => {
 
   it(`should work in a DSG page (exporting function named config)`, () => {
     cy.visit(page.dsg).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.dsg.base)
     cy.getTestElement(`title`).should(`have.text`, data.dsg.title)
+    cy.title().should(`eq`, data.dsg.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.dsg.meta)
@@ -96,10 +106,12 @@ describe(`Head function export html insertion`, () => {
 
   it(`should work in an SSR page (exporting function named getServerData)`, () => {
     cy.visit(page.ssr).waitForRouteChange()
+
     cy.getTestElement(`base`)
       .invoke(`attr`, `href`)
       .should(`equal`, data.ssr.base)
     cy.getTestElement(`title`).should(`have.text`, data.ssr.title)
+    cy.title().should(`eq`, data.ssr.title)
     cy.getTestElement(`meta`)
       .invoke(`attr`, `content`)
       .should(`equal`, data.ssr.meta)
diff --git a/e2e-tests/production-runtime/cypress/integration/head-function-export/typescript.js b/e2e-tests/production-runtime/cypress/integration/head-function-export/typescript.js
@@ -3,6 +3,7 @@ describe(`Tsx Pages`, () => {
     cy.visit(`/head-function-export/tsx-page`)
 
     cy.getTestElement(`title`).should(`contain`, `TypeScript`)
+    cy.title().should(`eq`, `TypeScript`)
 
     cy.getTestElement(`name`)
       .invoke(`attr`, `content`)
diff --git a/packages/gatsby/cache-dir/head/utils.js b/packages/gatsby/cache-dir/head/utils.js
@@ -156,9 +156,16 @@ export function getValidHeadNodesAndAttributes(
         let clonedNode = node.cloneNode(true)
         clonedNode.setAttribute(`data-gatsby-head`, true)
 
-        // // This is hack to make script tags work
+        // This is a hack to make script tags work
+        // TODO(serhalp): Explain what this is solving
         if (clonedNode.nodeName.toLowerCase() === `script`) {
-          clonedNode = massageScript(clonedNode)
+          clonedNode = cloneNodeWithoutNS(clonedNode)
+        }
+        // Recreate <title> elements in the HTML namespace to ensure `document.title` updates. When
+        // rendered inside an SVG (React 19 workaround), <title> elements inherit the SVG namespace
+        // (immutable on DOM nodes) and won't trigger an update of `document.title` when inserted in <head>.
+        if (clonedNode.nodeName.toLowerCase() === `title`) {
+          clonedNode = cloneNodeWithoutNS(clonedNode)
         }
         // Duplicate ids are not allowed in the head, so we need to dedupe them
         if (id) {
@@ -195,8 +202,13 @@ export function getValidHeadNodesAndAttributes(
   return { validHeadNodes, htmlAndBodyAttributes }
 }
 
-function massageScript(node) {
-  const script = document.createElement(`script`)
+/**
+ * Recreate an element in the HTML namespace.
+ *
+ * This is similar to `cloneNode()` but reinitializes immutable properties like the namespace.
+ */
+function cloneNodeWithoutNS(node) {
+  const script = document.createElement(node.nodeName)
   for (const attr of node.attributes) {
     script.setAttribute(attr.name, attr.value)
   }
