fix(react): dispose head entries on unmount in React 18 StrictMode (#664)

harlan-zw · web-flow · commit 50ffe371f10a · 2026-02-25T01:33:37.000+11:00
Moves entry creation from render-time (useRef init) into useEffect to avoid orphaned entries caused by React 18 StrictMode resetting refs between double-render invocations. Returns a stable proxy so callers get a consistent reference before the effect runs. Closes #558
diff --git a/packages/react/src/composables.ts b/packages/react/src/composables.ts
@@ -25,29 +25,39 @@ export function useUnhead(): Unhead {
 function withSideEffects<T extends ActiveHeadEntry<any>>(input: any, options: any, fn: any): T {
   const unhead = options.head || useUnhead()
   const entryRef = useRef<T | null>(null)
+  const inputRef = useRef(input)
+  inputRef.current = input
 
-  // Create entry only once, even in Strict Mode
-  if (!entryRef.current) {
-    entryRef.current = fn(unhead, input, options)
-  }
-
-  const entry = entryRef.current
-
-  // Patch entry when input changes
-  useEffect(() => {
-    entry?.patch(input)
-  }, [input, entry])
-
-  // Cleanup on unmount
+  // Create entry in effect to avoid orphaned entries in React 18 StrictMode.
+  // React 18 StrictMode resets useRef between its double-render invocations,
+  // so creating entries during render causes an orphaned entry that never gets disposed.
   useEffect(() => {
+    const entry = fn(unhead, inputRef.current, options) as T
+    entryRef.current = entry
     return () => {
-      entry?.dispose()
-      // Clear ref so new entry is created on remount
+      entry.dispose()
       entryRef.current = null
     }
-  }, [entry])
+  }, [unhead])
+
+  // Patch when input changes
+  useEffect(() => {
+    entryRef.current?.patch(input)
+  }, [input])
 
-  return entry as T
+  // Return a stable proxy that delegates to the real entry once created
+  const proxyRef = useRef<T | null>(null)
+  if (!proxyRef.current) {
+    proxyRef.current = {
+      patch: (newInput: any) => { entryRef.current?.patch(newInput) },
+      dispose: () => {
+        entryRef.current?.dispose()
+        entryRef.current = null
+      },
+      _poll: (rm?: boolean) => { entryRef.current?._poll(rm) },
+    } as T
+  }
+  return proxyRef.current
 }
 
 export function useHead(input: UseHeadInput = {}, options: HeadEntryOptions = {}): ActiveHeadEntry<UseHeadInput> {
diff --git a/packages/react/test/unmount-cleanup.test.tsx b/packages/react/test/unmount-cleanup.test.tsx
@@ -0,0 +1,194 @@
+// @vitest-environment jsdom
+import { act, fireEvent, render } from '@testing-library/react'
+import React, { useState } from 'react'
+import { describe, expect, it } from 'vitest'
+import { useHead } from '../src'
+import { createHead, renderDOMHead, UnheadProvider } from '../src/client'
+
+/**
+ * Reproduction of https://github.com/unjs/unhead/issues/558
+ * React 18 reporter says metadata persists after component unmount
+ */
+
+function Page1() {
+  useHead({
+    title: 'Page 1 title',
+    meta: [{ name: 'description', content: 'page 1 description' }],
+  })
+  return <div>Page 1</div>
+}
+
+function Page2() {
+  return <div>Page 2</div>
+}
+
+function App({ head }: { head: ReturnType<typeof createHead> }) {
+  const [currPage, setCurrPage] = useState<'Page 1' | 'Page 2'>('Page 2')
+  return (
+    <UnheadProvider head={head}>
+      <button onClick={() => setCurrPage('Page 1')}>Page 1</button>
+      <button onClick={() => setCurrPage('Page 2')}>Page 2</button>
+      {currPage === 'Page 1' ? <Page1 /> : <Page2 />}
+    </UnheadProvider>
+  )
+}
+
+function wait(ms = 10) {
+  return new Promise<void>(resolve => setTimeout(resolve, ms))
+}
+
+describe('issue #558 - unmount cleanup', () => {
+  it('restores init values after component unmount (DOM rendering)', async () => {
+    const head = createHead({
+      init: [{
+        title: 'Example fallback',
+        meta: [{ name: 'description', content: 'some description' }],
+      }],
+    })
+
+    const { getByText } = render(<App head={head} />)
+
+    // Initial DOM render
+    await act(async () => {
+      await renderDOMHead(head)
+      await wait()
+    })
+
+    expect(document.title).toBe('Example fallback')
+
+    // Switch to Page 1
+    await act(async () => {
+      fireEvent.click(getByText('Page 1'))
+      await wait()
+    })
+    await act(async () => {
+      await renderDOMHead(head)
+      await wait()
+    })
+
+    expect(document.title).toBe('Page 1 title')
+
+    // Switch back to Page 2
+    await act(async () => {
+      fireEvent.click(getByText('Page 2'))
+      await wait()
+    })
+    await act(async () => {
+      await renderDOMHead(head)
+      await wait()
+    })
+
+    expect(document.title).toBe('Example fallback')
+  })
+
+  it('handles multiple page switches correctly (DOM)', async () => {
+    const head = createHead({
+      init: [{
+        title: 'Fallback',
+        meta: [{ name: 'description', content: 'fallback desc' }],
+      }],
+    })
+
+    const { getByText } = render(<App head={head} />)
+
+    for (let i = 0; i < 3; i++) {
+      await act(async () => {
+        fireEvent.click(getByText('Page 1'))
+        await wait()
+      })
+      await act(async () => {
+        await renderDOMHead(head)
+        await wait()
+      })
+      expect(document.title).toBe('Page 1 title')
+
+      await act(async () => {
+        fireEvent.click(getByText('Page 2'))
+        await wait()
+      })
+      await act(async () => {
+        await renderDOMHead(head)
+        await wait()
+      })
+      expect(document.title).toBe('Fallback')
+    }
+  })
+
+  it('direct unmount restores init values (DOM)', async () => {
+    const head = createHead({
+      init: [{
+        title: 'Init Title',
+        meta: [{ name: 'description', content: 'init description' }],
+      }],
+    })
+
+    function PageWithHead() {
+      useHead({
+        title: 'Component Title',
+        meta: [{ name: 'description', content: 'component description' }],
+      })
+      return <div>Has Head</div>
+    }
+
+    const { unmount } = render(
+      <UnheadProvider head={head}>
+        <PageWithHead />
+      </UnheadProvider>,
+    )
+
+    await act(async () => {
+      await renderDOMHead(head)
+      await wait()
+    })
+
+    expect(document.title).toBe('Component Title')
+
+    await act(async () => {
+      unmount()
+      await wait()
+    })
+    await act(async () => {
+      await renderDOMHead(head)
+      await wait()
+    })
+
+    expect(document.title).toBe('Init Title')
+  })
+
+  it('entries state is correct through mount/unmount cycle', async () => {
+    const head = createHead({
+      init: [{
+        title: 'Init',
+      }],
+    })
+
+    function PageWithHead() {
+      useHead({ title: 'Component' })
+      return <div>Has Head</div>
+    }
+
+    // Initially, only init entry
+    expect(head.entries.size).toBe(1)
+
+    const { unmount } = render(
+      <UnheadProvider head={head}>
+        <PageWithHead />
+      </UnheadProvider>,
+    )
+
+    await act(async () => {
+      await wait()
+    })
+
+    // After mount, should have 2 entries
+    expect(head.entries.size).toBe(2)
+
+    await act(async () => {
+      unmount()
+      await wait()
+    })
+
+    // After unmount, back to 1 entry (init only)
+    expect(head.entries.size).toBe(1)
+  })
+})
