From 6e882eb731e8b3135079c702f1cb91c85d0d0720 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 11:48:57 -0500
Subject: [PATCH 01/15] =?UTF-8?q?Revert=20"perf(useRefObjectAsForwardedRef?=
 =?UTF-8?q?):=20add=20dependency=20array=20to=20useImperati=E2=80=A6"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This reverts commit 6225ba231cfdbe6ef7fa41dd62734d5a970bdc7d.
---
 packages/react/src/hooks/useRefObjectAsForwardedRef.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
index 2d1fb01f0a7..11becf147d7 100644
--- a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
+++ b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
@@ -9,7 +9,5 @@ import {useImperativeHandle} from 'react'
  * **NOTE**: The `refObject` should be passed to the underlying element, NOT the `forwardedRef`.
  */
 export function useRefObjectAsForwardedRef<T>(forwardedRef: ForwardedRef<T>, refObject: RefObject<T | null>): void {
-  // The ref object is stable (from useRef), so this factory only needs to run once.
-  // Without the dependency array, useImperativeHandle re-runs the factory every render.
-  useImperativeHandle<T | null, T | null>(forwardedRef, () => refObject.current, [refObject])
+  useImperativeHandle<T | null, T | null>(forwardedRef, () => refObject.current)
 }

From 288dee92b49169d3280ce4a50318963acb9c6de2 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 18:21:48 +0000
Subject: [PATCH 02/15] Add unit tests

---
 .../useRefObjectAsForwardedRef.test.tsx       | 103 ++++++++++++++++++
 1 file changed, 103 insertions(+)
 create mode 100644 packages/react/src/hooks/__tests__/useRefObjectAsForwardedRef.test.tsx

diff --git a/packages/react/src/hooks/__tests__/useRefObjectAsForwardedRef.test.tsx b/packages/react/src/hooks/__tests__/useRefObjectAsForwardedRef.test.tsx
new file mode 100644
index 00000000000..9a6e72538ad
--- /dev/null
+++ b/packages/react/src/hooks/__tests__/useRefObjectAsForwardedRef.test.tsx
@@ -0,0 +1,103 @@
+import {render} from '@testing-library/react'
+import React, {forwardRef, type RefObject} from 'react'
+import {describe, expect, it, vi} from 'vitest'
+import {useRefObjectAsForwardedRef} from '../useRefObjectAsForwardedRef'
+
+type InputOrButtonRef = RefObject<HTMLInputElement & HTMLButtonElement>
+
+const Component = forwardRef<HTMLInputElement & HTMLButtonElement, {asButton?: boolean}>(({asButton}, forwardedRef) => {
+  const ref: InputOrButtonRef = React.useRef(null)
+
+  useRefObjectAsForwardedRef(forwardedRef, ref)
+
+  return asButton ? <button type="button" ref={ref} /> : <input ref={ref} />
+})
+
+describe('useRefObjectAsForwardedRef', () => {
+  describe('object refs', () => {
+    it('fowards the ref to the underlying element', async () => {
+      const ref: InputOrButtonRef = {current: null}
+
+      render(<Component ref={ref} />)
+
+      expect(ref.current).toBeInstanceOf(HTMLInputElement)
+    })
+
+    it('avoids dangling references by clearing the ref on unmount', () => {
+      const ref: InputOrButtonRef = {current: null}
+
+      const {unmount} = render(<Component ref={ref} />)
+
+      expect(ref.current).toBeInstanceOf(HTMLInputElement)
+
+      unmount()
+
+      expect(ref.current).toBeNull()
+    })
+
+    it('updates the ref if the target changes', () => {
+      const ref: InputOrButtonRef = {current: null}
+
+      const {rerender} = render(<Component ref={ref} />)
+
+      expect(ref.current).toBeInstanceOf(HTMLInputElement)
+
+      rerender(<Component ref={ref} asButton />)
+
+      expect(ref.current).toBeInstanceOf(HTMLButtonElement)
+    })
+
+    it('is correctly set during an initial effect', () => {
+      // This can break if the hook delays setting the initial value until a subsequent render
+
+      const ComponentWithEffect = () => {
+        const ref = React.useRef<HTMLInputElement & HTMLButtonElement>(null)
+
+        React.useEffect(() => {
+          expect(ref.current).toBeInstanceOf(HTMLInputElement)
+        }, [])
+
+        return <Component ref={ref} />
+      }
+
+      render(<ComponentWithEffect />)
+    })
+  })
+
+  describe('callback refs', () => {
+    it('calls the ref on mount and unmount', async () => {
+      const ref = vi.fn()
+
+      const {unmount} = render(<Component ref={ref} />)
+
+      expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement))
+
+      unmount()
+
+      expect(ref).toHaveBeenCalledWith(null)
+    })
+
+    it('calls the ref if the target changes', () => {
+      const ref = vi.fn()
+
+      const {rerender} = render(<Component ref={ref} />)
+
+      expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement))
+
+      rerender(<Component ref={ref} asButton />)
+
+      expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
+    })
+
+    // Known issue: The ref is called on every render, even if the target does not change
+    it.todo('does not call the ref on re-render if the target does not change', () => {
+      const ref = vi.fn()
+
+      const {rerender} = render(<Component ref={ref} />)
+
+      rerender(<Component ref={ref} />)
+
+      expect(ref).toHaveBeenCalledExactlyOnceWith(expect.any(HTMLInputElement))
+    })
+  })
+})

From 8fea4b79dffbc19ec3c9e3a9cb6e831df95c908a Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 21:43:24 +0000
Subject: [PATCH 03/15] Add `useCombinedRefs` and deprecate
 `useRefObjectAsForwardedRefs`

---
 .../__snapshots__/exports.test.ts.snap        |   1 +
 .../hooks/__tests__/useCombinedRefs.test.tsx  | 137 ++++++++++++++++++
 packages/react/src/hooks/index.ts             |   1 +
 .../src/hooks/useCombinedRefs.hookDocs.json   |  20 +++
 packages/react/src/hooks/useCombinedRefs.ts   |  81 +++++++++++
 .../src/hooks/useRefObjectAsForwardedRef.ts   |  33 ++++-
 packages/react/src/index.ts                   |   1 +
 7 files changed, 272 insertions(+), 2 deletions(-)
 create mode 100644 packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
 create mode 100644 packages/react/src/hooks/useCombinedRefs.hookDocs.json
 create mode 100644 packages/react/src/hooks/useCombinedRefs.ts

diff --git a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
index 77f3b55f2a2..6082f2ed77a 100644
--- a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -224,6 +224,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useOverlay",
   "useProvidedRefOrCreate",
   "useRefObjectAsForwardedRef",
+  "useCombinedRefs",
   "useResizeObserver",
   "useResponsiveValue",
   "useSafeTimeout",
diff --git a/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx b/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
new file mode 100644
index 00000000000..d6f1f52df2e
--- /dev/null
+++ b/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
@@ -0,0 +1,137 @@
+import {render, renderHook} from '@testing-library/react'
+import React, {forwardRef, type RefObject} from 'react'
+import {describe, expect, it, vi} from 'vitest'
+import {useCombinedRefs} from '../useCombinedRefs'
+
+type InputOrButtonRef = RefObject<HTMLInputElement & HTMLButtonElement>
+
+const Component = forwardRef<HTMLInputElement & HTMLButtonElement, {asButton?: boolean}>(({asButton}, forwardedRef) => {
+  const ref: InputOrButtonRef = React.useRef(null)
+
+  const combinedRef = useCombinedRefs(forwardedRef, ref)
+
+  return asButton ? <button type="button" ref={combinedRef} /> : <input ref={combinedRef} />
+})
+
+describe('useCombinedRefs', () => {
+  describe('combining a forwarded ref with an internal ref', () => {
+    describe('object refs', () => {
+      it('fowards the ref to the underlying element', async () => {
+        const ref: InputOrButtonRef = {current: null}
+
+        render(<Component ref={ref} />)
+
+        expect(ref.current).toBeInstanceOf(HTMLInputElement)
+      })
+
+      it('avoids dangling references by clearing the ref on unmount', () => {
+        const ref: InputOrButtonRef = {current: null}
+
+        const {unmount} = render(<Component ref={ref} />)
+
+        expect(ref.current).toBeInstanceOf(HTMLInputElement)
+
+        unmount()
+
+        expect(ref.current).toBeNull()
+      })
+
+      it('updates the ref if the target changes', () => {
+        const ref: InputOrButtonRef = {current: null}
+
+        const {rerender} = render(<Component ref={ref} />)
+
+        expect(ref.current).toBeInstanceOf(HTMLInputElement)
+
+        rerender(<Component ref={ref} asButton />)
+
+        expect(ref.current).toBeInstanceOf(HTMLButtonElement)
+      })
+
+      it('is correctly set during an initial effect', () => {
+        // This can break if the hook delays setting the initial value until a subsequent render
+
+        const ComponentWithEffect = () => {
+          const ref = React.useRef<HTMLInputElement & HTMLButtonElement>(null)
+
+          React.useEffect(() => {
+            expect(ref.current).toBeInstanceOf(HTMLInputElement)
+          }, [])
+
+          return <Component ref={ref} />
+        }
+
+        render(<ComponentWithEffect />)
+      })
+    })
+
+    describe('callback refs', () => {
+      it('calls the ref on mount and unmount', async () => {
+        const ref = vi.fn()
+
+        const {unmount} = render(<Component ref={ref} />)
+
+        expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement))
+
+        unmount()
+
+        expect(ref).toHaveBeenCalledWith(null)
+      })
+
+      it('calls the ref if the target changes', () => {
+        const ref = vi.fn()
+
+        const {rerender} = render(<Component ref={ref} />)
+
+        expect(ref).toHaveBeenCalledWith(expect.any(HTMLInputElement))
+
+        rerender(<Component ref={ref} asButton />)
+
+        expect(ref).toHaveBeenCalledWith(expect.any(HTMLButtonElement))
+      })
+
+      it('does not call the ref on re-render if the target does not change', () => {
+        const ref = vi.fn()
+
+        const {rerender} = render(<Component ref={ref} />)
+
+        rerender(<Component ref={ref} />)
+
+        expect(ref).toHaveBeenCalledExactlyOnceWith(expect.any(HTMLInputElement))
+      })
+    })
+  })
+
+  describe('combining two callback refs', () => {
+    it('calls both refs when the combined ref is called', () => {
+      const refA = vi.fn()
+      const refB = vi.fn()
+
+      const combined = renderHook(() => useCombinedRefs(refA, refB))
+
+      combined.result.current('test')
+      expect(refA).toHaveBeenCalledExactlyOnceWith('test')
+      expect(refB).toHaveBeenCalledExactlyOnceWith('test')
+    })
+
+    it('handles cleanup functions correctly and independently', () => {
+      const refA = vi.fn()
+      const cleanupRefB = vi.fn()
+      const refB = vi.fn().mockReturnValue(cleanupRefB)
+
+      const combined = renderHook(() => useCombinedRefs(refA, refB))
+
+      combined.result.current('test')
+      expect(refA).toHaveBeenCalledWith('test')
+      expect(refB).toHaveBeenCalledWith('test')
+
+      combined.result.current(null)
+      expect(refA).toHaveBeenCalledWith(null)
+      expect(refB).not.toHaveBeenCalledWith(null)
+      expect(cleanupRefB).not.toHaveBeenCalled()
+
+      combined.unmount()
+      expect(cleanupRefB).toHaveBeenCalledOnce()
+    })
+  })
+})
diff --git a/packages/react/src/hooks/index.ts b/packages/react/src/hooks/index.ts
index d8259f5fd96..4475654829c 100644
--- a/packages/react/src/hooks/index.ts
+++ b/packages/react/src/hooks/index.ts
@@ -14,5 +14,6 @@ export {useMenuInitialFocus} from './useMenuInitialFocus'
 export {useMenuKeyboardNavigation} from './useMenuKeyboardNavigation'
 export {useMnemonics} from './useMnemonics'
 export {useRefObjectAsForwardedRef} from './useRefObjectAsForwardedRef'
+export {useCombinedRefs} from './useCombinedRefs'
 export {useId} from './useId'
 export {useIsMacOS} from './useIsMacOS'
diff --git a/packages/react/src/hooks/useCombinedRefs.hookDocs.json b/packages/react/src/hooks/useCombinedRefs.hookDocs.json
new file mode 100644
index 00000000000..efbf596c897
--- /dev/null
+++ b/packages/react/src/hooks/useCombinedRefs.hookDocs.json
@@ -0,0 +1,20 @@
+{
+  "name": "useCombinedRefs",
+  "importPath": "@primer/react",
+  "stories": [],
+  "parameters": [
+    {
+      "name": "refA",
+      "derive": true,
+      "description": "First ref to combine."
+    },
+    {
+      "name": "refB",
+      "derive": true,
+      "description": "Second ref to combine."
+    }
+  ],
+  "returns": {
+    "derive": true
+  }
+}
diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
new file mode 100644
index 00000000000..d22071e4c80
--- /dev/null
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -0,0 +1,81 @@
+import type {ForwardedRef, Ref as NormalRef, MutableRefObject} from 'react'
+import {useCallback, useEffect, useRef} from 'react'
+
+type CleanupFunction = () => void
+
+/**
+ * React 19 supports callback refs that can return a cleanup function. If a cleanup function is returned, the
+ * cleanup is called on unmount **instead** of setting the ref to null.
+ */
+// bivarianceHack copied from React types
+type React19RefCallback<T> = {
+  bivarianceHack(instance: T): void | CleanupFunction
+}['bivarianceHack']
+
+// Allowing `undefined` makes it easier to handle React 19 ref-as-prop where the ref prop is optional without having to default to `null`
+type Ref<T> = ForwardedRef<T> | React19RefCallback<T> | NormalRef<T> | undefined
+
+function setRef<T>(ref: Ref<T>, value: T, cleanupRef: MutableRefObject<CleanupFunction | undefined>) {
+  // NOTE: This is technically incorrect; in React 19 even with a callback ref it should be possible to call a ref with
+  // `null` if it happens before unmount. But there's no way for a callback react to know whether this update is happening
+  // during unmount or not, because we are trying to still be cross-compatible with React 18. Once we only need to support
+  // React 19, this can be corrected using a cleanup callback in our own combined ref.
+  if (value === null && cleanupRef.current) return
+
+  if (typeof ref === 'function') {
+    const cleanup = ref(value)
+    cleanupRef.current = cleanup || undefined
+  } else if (ref) {
+    // `React.Ref` is typed as immutable to protect consumers but it's OK to mutate it here. We could just change the
+    // type to only accept mutable refs, but then it would be harder to accept refs as props in React 19 because we
+    // would have to use the `React.ForwardedRef` type instead of `React.Ref`
+    ;(ref as MutableRefObject<T>).current = value
+  }
+}
+
+/**
+ * Combine two refs of matching type (typically an external or forwarded ref and an internal `useRef` object or
+ * callback ref). Returns a new ref which must be passed to the relevant component.
+ *
+ * If you need to combine more than two refs (what are you doing?) just nest the hook: useCombinedRefs(refA, useCombinedRefs(refB, refC))
+ *
+ * @param refA First ref to combine. The order is not important.
+ * @param refB Second ref to combine. The order is not important.
+ *
+ * @example
+ * // React 18
+ * const Example = forwardRef<HTMLButtonElement, {}>((props, forwardedRef) => {
+ *  const ref = useRef<HTMLButtonElement>(null)
+ *
+ *  return <button ref={useCombinedRefs(forwardedRef, ref)} />
+ * })
+ *
+ * @example
+ * // React 19
+ * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
+ *  const ref = useRef<HTMLButtonElement>(null)
+ *
+ *  return <button ref={useCombinedRefs(ref, externalRef)} />
+ * }
+ */
+export function useCombinedRefs<T>(refA: Ref<T>, refB: Ref<T>) {
+  const cleanupARef = useRef<CleanupFunction>()
+  const cleanupBRef = useRef<CleanupFunction>()
+
+  // Call React 19 cleanup ref callbacks only on unmount
+  useEffect(
+    () => () => {
+      cleanupARef.current?.()
+      cleanupBRef.current?.()
+    },
+    [],
+  )
+
+  return useCallback(
+    (value: T | null) => {
+      setRef(refA, value, cleanupARef)
+      setRef(refB, value, cleanupBRef)
+    },
+    [refA, refB],
+  )
+}
diff --git a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
index 11becf147d7..8aee421822b 100644
--- a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
+++ b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
@@ -1,5 +1,7 @@
 import type {ForwardedRef, RefObject} from 'react'
-import {useImperativeHandle} from 'react'
+import {useImperativeHandle, useMemo} from 'react'
+
+const unset = Symbol()
 
 /**
  * Use a ref object as the imperative handle for a forwarded ref. This can be used to
@@ -7,7 +9,34 @@ import {useImperativeHandle} from 'react'
  * instance with `.current`.
  *
  * **NOTE**: The `refObject` should be passed to the underlying element, NOT the `forwardedRef`.
+ *
+ * @deprecated Migrate to `useCombinedRefs`. It's safer, faster, and easier to use:
+ *
+ * ```diff
+ *   const ref = useRef(null)
+ *
+ * - useRefObjectAsForwardedRef(forwardedRef, ref)
+ * + const combinedRef = useCombinedRefs(forwardedRef, ref)
+ *
+ * - return <div ref={ref} />
+ * + return <div ref={combinedRef} />
+ * ```
  */
 export function useRefObjectAsForwardedRef<T>(forwardedRef: ForwardedRef<T>, refObject: RefObject<T | null>): void {
-  useImperativeHandle<T | null, T | null>(forwardedRef, () => refObject.current)
+  const wrappedForwardedRef: ForwardedRef<T> = useMemo(() => {
+    if (typeof forwardedRef === 'function') {
+      let lastInstance: T | null | typeof unset = unset
+
+      return (instance: T | null) => {
+        if (instance !== lastInstance) {
+          lastInstance = instance
+          forwardedRef(instance)
+        }
+      }
+    }
+
+    return forwardedRef
+  }, [forwardedRef])
+
+  useImperativeHandle<T | null, T | null>(wrappedForwardedRef, () => refObject.current)
 }
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 66c8d438e12..dd6506bc36e 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -39,6 +39,7 @@ export type {FocusTrapHookSettings} from './hooks/useFocusTrap'
 export {useFocusZone} from './hooks/useFocusZone'
 export type {FocusZoneHookSettings} from './hooks/useFocusZone'
 export {useRefObjectAsForwardedRef} from './hooks/useRefObjectAsForwardedRef'
+export {useCombinedRefs} from './hooks/useCombinedRefs'
 export {useResizeObserver} from './hooks/useResizeObserver'
 export {useResponsiveValue, type ResponsiveValue} from './hooks/useResponsiveValue'
 export {default as useIsomorphicLayoutEffect} from './utils/useIsomorphicLayoutEffect'

From 3b9804fc213c58ceaac29f0dd5ba20db6f26a4ff Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 21:54:19 +0000
Subject: [PATCH 04/15] Migrate Primer components to `useCombinedRefs`

---
 .../src/Autocomplete/AutocompleteInput.tsx    |  6 +-
 .../src/Autocomplete/AutocompleteOverlay.tsx  |  6 +-
 packages/react/src/Button/ButtonBase.tsx      |  4 +-
 packages/react/src/Dialog/Dialog.tsx          |  4 +-
 packages/react/src/Heading/Heading.tsx        |  4 +-
 packages/react/src/Link/Link.tsx              |  7 +-
 packages/react/src/Overlay/Overlay.tsx        |  6 +-
 packages/react/src/PageLayout/PageLayout.tsx  | 10 +--
 .../TextInputWithTokens.tsx                   |  6 +-
 .../react/src/deprecated/DialogV1/Dialog.tsx  |  4 +-
 packages/react/src/hooks/useCombinedRefs.ts   | 88 +++++++++++--------
 11 files changed, 79 insertions(+), 66 deletions(-)

diff --git a/packages/react/src/Autocomplete/AutocompleteInput.tsx b/packages/react/src/Autocomplete/AutocompleteInput.tsx
index 61b2905e5ba..3bcac66dd80 100644
--- a/packages/react/src/Autocomplete/AutocompleteInput.tsx
+++ b/packages/react/src/Autocomplete/AutocompleteInput.tsx
@@ -3,7 +3,7 @@ import React, {useCallback, useContext, useEffect, useState} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {AutocompleteContext, AutocompleteInputContext} from './AutocompleteContext'
 import TextInput from '../TextInput'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import type {ComponentProps} from '../utils/types'
 import useSafeTimeout from '../hooks/useSafeTimeout'
 
@@ -43,7 +43,7 @@ const AutocompleteInput = React.forwardRef(
     }
     const {activeDescendantRef, id, inputRef, setInputValue, setShowMenu, showMenu} = autocompleteContext
     const {autocompleteSuggestion = '', inputValue = '', isMenuDirectlyActivated} = inputContext
-    useRefObjectAsForwardedRef(forwardedRef, inputRef)
+    const combinedRef = useCombinedRefs(forwardedRef, inputRef)
     const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
     const {safeSetTimeout} = useSafeTimeout()
 
@@ -160,7 +160,7 @@ const AutocompleteInput = React.forwardRef(
         onKeyDown={handleInputKeyDown}
         onKeyPress={onInputKeyPress}
         onKeyUp={handleInputKeyUp}
-        ref={inputRef}
+        ref={combinedRef}
         aria-controls={`${id}-listbox`}
         aria-autocomplete="both"
         role="combobox"
diff --git a/packages/react/src/Autocomplete/AutocompleteOverlay.tsx b/packages/react/src/Autocomplete/AutocompleteOverlay.tsx
index 0755434225e..203b4e6bcde 100644
--- a/packages/react/src/Autocomplete/AutocompleteOverlay.tsx
+++ b/packages/react/src/Autocomplete/AutocompleteOverlay.tsx
@@ -5,7 +5,7 @@ import type {OverlayProps} from '../Overlay'
 import Overlay from '../Overlay'
 import type {ComponentProps} from '../utils/types'
 import {AutocompleteContext} from './AutocompleteContext'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import VisuallyHidden from '../_VisuallyHidden'
 
 import classes from './AutocompleteOverlay.module.css'
@@ -57,7 +57,7 @@ function AutocompleteOverlay({
     [showMenu, selectedItemLength],
   )
 
-  useRefObjectAsForwardedRef(scrollContainerRef, floatingElementRef)
+  const combinedRef = useCombinedRefs(scrollContainerRef, floatingElementRef)
 
   const closeOptionList = useCallback(() => {
     setShowMenu(false)
@@ -73,7 +73,7 @@ function AutocompleteOverlay({
       preventFocusOnOpen={true}
       onClickOutside={closeOptionList}
       onEscape={closeOptionList}
-      ref={floatingElementRef as React.RefObject<HTMLDivElement>}
+      ref={combinedRef}
       top={position?.top}
       left={position?.left}
       className={clsx(classes.Overlay, className)}
diff --git a/packages/react/src/Button/ButtonBase.tsx b/packages/react/src/Button/ButtonBase.tsx
index aa337e32ea7..ceaad3f39a8 100644
--- a/packages/react/src/Button/ButtonBase.tsx
+++ b/packages/react/src/Button/ButtonBase.tsx
@@ -1,7 +1,7 @@
 import React, {forwardRef, type JSX} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import type {ButtonProps} from './types'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import {VisuallyHidden} from '../VisuallyHidden'
 import Spinner from '../Spinner'
 import CounterLabel from '../CounterLabel'
@@ -51,7 +51,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
   } = props
 
   const innerRef = React.useRef<HTMLButtonElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  useCombinedRefs(forwardedRef, innerRef)
 
   const uuid = useId(id)
   const loadingAnnouncementID = `${uuid}-loading-announcement`
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
index 2a070a88d66..ee72b754d33 100644
--- a/packages/react/src/Dialog/Dialog.tsx
+++ b/packages/react/src/Dialog/Dialog.tsx
@@ -7,7 +7,7 @@ import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {FocusKeys} from '@primer/behaviors'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import {useId} from '../hooks/useId'
 import {ScrollableRegion} from '../ScrollableRegion'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -288,7 +288,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
   })
 
   const dialogRef = useRef<HTMLDivElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, dialogRef)
+  useCombinedRefs(forwardedRef, dialogRef)
   const backdropRef = useRef<HTMLDivElement>(null)
 
   useFocusTrap({
diff --git a/packages/react/src/Heading/Heading.tsx b/packages/react/src/Heading/Heading.tsx
index 474a49ede24..a7af94443d6 100644
--- a/packages/react/src/Heading/Heading.tsx
+++ b/packages/react/src/Heading/Heading.tsx
@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {forwardRef, useEffect} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import type {ComponentProps} from '../utils/types'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Heading.module.css'
@@ -14,7 +14,7 @@ type StyledHeadingProps = {
 
 const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  useCombinedRefs(forwardedRef, innerRef)
 
   if (__DEV__) {
     /**
diff --git a/packages/react/src/Link/Link.tsx b/packages/react/src/Link/Link.tsx
index 1680afb2eb1..c4f16e0c90b 100644
--- a/packages/react/src/Link/Link.tsx
+++ b/packages/react/src/Link/Link.tsx
@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {useEffect, type ForwardedRef, type ElementRef} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import classes from './Link.module.css'
 import type {ComponentProps} from '../utils/types'
 import {type PolymorphicProps, fixedForwardRef} from '../utils/modern-polymorphic'
@@ -20,7 +20,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
 ) => {
   const {as: Component = 'a', className, inline, hoverColor, ...restProps} = props
   const innerRef = React.useRef<ElementRef<As>>(null)
-  useRefObjectAsForwardedRef(ref, innerRef)
+  const combinedRef = useCombinedRefs(ref, innerRef)
 
   if (__DEV__) {
     /**
@@ -53,8 +53,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
       data-inline={inline}
       data-hover-color={hoverColor}
       {...restProps}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ref={innerRef as any}
+      ref={combinedRef}
     />
   )
 }
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
index 362083945e2..6c9e67568b8 100644
--- a/packages/react/src/Overlay/Overlay.tsx
+++ b/packages/react/src/Overlay/Overlay.tsx
@@ -5,7 +5,7 @@ import type {AriaRole, Merge} from '../utils/types'
 import type {TouchOrMouseEvent} from '../hooks'
 import {useOverlay} from '../hooks'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import type {AnchorSide} from '@primer/behaviors'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Overlay.module.css'
@@ -190,7 +190,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
     const overlayRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, overlayRef)
+    const combinedRef = useCombinedRefs(forwardedRef, overlayRef)
     const slideAnimationDistance = 8 // var(--base-size-8), hardcoded to do some math
     const slideAnimationEasing = 'cubic-bezier(0.33, 1, 0.68, 1)'
 
@@ -235,7 +235,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
           role={role}
           width={width}
           data-reflow-container={!preventOverflow ? true : undefined}
-          ref={overlayRef}
+          ref={combinedRef}
           left={leftPosition}
           right={right}
           height={height}
diff --git a/packages/react/src/PageLayout/PageLayout.tsx b/packages/react/src/PageLayout/PageLayout.tsx
index 1120e8c6895..cde829e9e41 100644
--- a/packages/react/src/PageLayout/PageLayout.tsx
+++ b/packages/react/src/PageLayout/PageLayout.tsx
@@ -1,7 +1,7 @@
 import React, {memo, useRef} from 'react'
 import {clsx} from 'clsx'
 import {useId} from '../hooks/useId'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
 import {isResponsiveValue} from '../hooks/useResponsiveValue'
 import {useSlots} from '../hooks/useSlots'
@@ -868,7 +868,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
         currentWidth: controlledWidth,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, paneRef)
+    const combinedRef = useCombinedRefs(forwardRef, paneRef)
 
     const hasOverflow = useOverflow(paneRef)
 
@@ -917,7 +917,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
           position={positionProp}
         />
         <div
-          ref={paneRef}
+          ref={combinedRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           // Not needed when onResizeEnd is provided (localStorage isn't read).
@@ -1166,7 +1166,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
         constrainToViewport: true,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, sidebarRef)
+    const combinedRef = useCombinedRefs(forwardRef, sidebarRef)
 
     const hasOverflow = useOverflow(sidebarRef)
 
@@ -1222,7 +1222,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
           />
         )}
         <div
-          ref={sidebarRef}
+          ref={combinedRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           suppressHydrationWarning={resizable === true && !!widthStorageKey}
diff --git a/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx b/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx
index 8031d87a4d5..dfafee0df50 100644
--- a/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx
+++ b/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx
@@ -3,7 +3,7 @@ import {isFocusable} from '@primer/behaviors/utils'
 import type {FocusEventHandler, KeyboardEventHandler, MouseEventHandler, RefObject} from 'react'
 import React, {useRef, useState} from 'react'
 import {isValidElementType} from 'react-is'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../hooks/useCombinedRefs'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import Text from '../Text'
@@ -108,7 +108,7 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
   const ref = useRef<HTMLInputElement>(null)
 
   const selectedValuesDescriptionId = useId()
-  useRefObjectAsForwardedRef(forwardedRef, ref)
+  const combinedRef = useCombinedRefs(forwardedRef, ref)
   const [selectedTokenIndex, setSelectedTokenIndex] = useState<number | undefined>()
   const [tokensAreTruncated, setTokensAreTruncated] = useState<boolean>(Boolean(visibleTokenCount))
   const selectedTokenTexts = tokens
@@ -310,7 +310,7 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
       >
         <div className={styles.InputWrapper}>
           <UnstyledTextInput
-            ref={ref}
+            ref={combinedRef}
             disabled={disabled}
             onFocus={handleInputFocus}
             onBlur={handleInputBlur}
diff --git a/packages/react/src/deprecated/DialogV1/Dialog.tsx b/packages/react/src/deprecated/DialogV1/Dialog.tsx
index caad7a4ab2c..50497303fe2 100644
--- a/packages/react/src/deprecated/DialogV1/Dialog.tsx
+++ b/packages/react/src/deprecated/DialogV1/Dialog.tsx
@@ -2,7 +2,7 @@ import React, {forwardRef, useRef, type HTMLAttributes} from 'react'
 import {IconButton} from '../../Button'
 import useDialog from '../../hooks/useDialog'
 import type {ComponentProps} from '../../utils/types'
-import {useRefObjectAsForwardedRef} from '../../hooks/useRefObjectAsForwardedRef'
+import {useCombinedRefs} from '../../hooks/useCombinedRefs'
 import {XIcon} from '@primer/octicons-react'
 import {clsx} from 'clsx'
 import classes from './Dialog.module.css'
@@ -48,7 +48,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
   ) => {
     const overlayRef = useRef(null)
     const modalRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, modalRef)
+    useCombinedRefs(forwardedRef, modalRef)
     const closeButtonRef = useRef(null)
 
     const onCloseClick = () => {
diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
index d22071e4c80..b36f3144e25 100644
--- a/packages/react/src/hooks/useCombinedRefs.ts
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -1,61 +1,34 @@
-import type {ForwardedRef, Ref as NormalRef, MutableRefObject} from 'react'
+import type {ForwardedRef, Ref as StandardRef, MutableRefObject} from 'react'
 import {useCallback, useEffect, useRef} from 'react'
 
-type CleanupFunction = () => void
-
-/**
- * React 19 supports callback refs that can return a cleanup function. If a cleanup function is returned, the
- * cleanup is called on unmount **instead** of setting the ref to null.
- */
-// bivarianceHack copied from React types
-type React19RefCallback<T> = {
-  bivarianceHack(instance: T): void | CleanupFunction
-}['bivarianceHack']
-
-// Allowing `undefined` makes it easier to handle React 19 ref-as-prop where the ref prop is optional without having to default to `null`
-type Ref<T> = ForwardedRef<T> | React19RefCallback<T> | NormalRef<T> | undefined
-
-function setRef<T>(ref: Ref<T>, value: T, cleanupRef: MutableRefObject<CleanupFunction | undefined>) {
-  // NOTE: This is technically incorrect; in React 19 even with a callback ref it should be possible to call a ref with
-  // `null` if it happens before unmount. But there's no way for a callback react to know whether this update is happening
-  // during unmount or not, because we are trying to still be cross-compatible with React 18. Once we only need to support
-  // React 19, this can be corrected using a cleanup callback in our own combined ref.
-  if (value === null && cleanupRef.current) return
-
-  if (typeof ref === 'function') {
-    const cleanup = ref(value)
-    cleanupRef.current = cleanup || undefined
-  } else if (ref) {
-    // `React.Ref` is typed as immutable to protect consumers but it's OK to mutate it here. We could just change the
-    // type to only accept mutable refs, but then it would be harder to accept refs as props in React 19 because we
-    // would have to use the `React.ForwardedRef` type instead of `React.Ref`
-    ;(ref as MutableRefObject<T>).current = value
-  }
-}
-
 /**
  * Combine two refs of matching type (typically an external or forwarded ref and an internal `useRef` object or
- * callback ref). Returns a new ref which must be passed to the relevant component.
+ * callback ref).
  *
- * If you need to combine more than two refs (what are you doing?) just nest the hook: useCombinedRefs(refA, useCombinedRefs(refB, refC))
+ * If you need to combine more than two refs (what are you doing?) just nest the hook:
+ * `useCombinedRefs(refA, useCombinedRefs(refB, refC))`
  *
  * @param refA First ref to combine. The order is not important.
  * @param refB Second ref to combine. The order is not important.
+ * @returns A new ref which must be passed to the relevant child component. **Important**: do not pass `refA` or
+ * `refB` to the component!
  *
  * @example
  * // React 18
  * const Example = forwardRef<HTMLButtonElement, {}>((props, forwardedRef) => {
  *  const ref = useRef<HTMLButtonElement>(null)
+ *  const combinedRef = useCombinedRefs(forwardedRef, ref)
  *
- *  return <button ref={useCombinedRefs(forwardedRef, ref)} />
+ *  return <button ref={combinedRef} />
  * })
  *
  * @example
  * // React 19
  * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
  *  const ref = useRef<HTMLButtonElement>(null)
+ *  const combinedRef = useCombinedRefs(forwardedRef, ref)
  *
- *  return <button ref={useCombinedRefs(ref, externalRef)} />
+ *  return <button ref={combinedRef} />
  * }
  */
 export function useCombinedRefs<T>(refA: Ref<T>, refB: Ref<T>) {
@@ -75,7 +48,48 @@ export function useCombinedRefs<T>(refA: Ref<T>, refB: Ref<T>) {
     (value: T | null) => {
       setRef(refA, value, cleanupARef)
       setRef(refB, value, cleanupBRef)
+
+      // When we drop support for React 18 we can just handle cleanup here with a returned function
     },
     [refA, refB],
   )
 }
+
+type CleanupFunction = () => void
+
+/**
+ * React 19 supports callback refs that can return a cleanup function. If a cleanup function is returned, the
+ * cleanup is called on unmount **instead** of setting the ref to null.
+ */
+// bivarianceHack copied from React types
+type React19RefCallback<T> = {
+  bivarianceHack(instance: T): void | CleanupFunction
+}['bivarianceHack']
+
+/**
+ * Supporting React 18 and 19 while alleviating the need for any hacks or casts in consumers:
+ * - `ForwardedRef` from the React 18 `forwardRef` HOC
+ * - `React19RefCallback` for callback refs that can return a cleanup function (this is included in `Ref` in React 19
+ *   but not in 18)
+ * - `Ref` for standard refs from `useRef` or passed in as React 19 prop
+ * - `undefined` to allow for easy use of optional `ref` props in React 19
+ */
+type Ref<T> = ForwardedRef<T> | React19RefCallback<T> | StandardRef<T> | undefined
+
+function setRef<T>(ref: Ref<T>, value: T, cleanupRef: MutableRefObject<CleanupFunction | undefined>) {
+  // NOTE: This is technically incorrect; in React 19 even with a callback ref it should be possible to call a ref with
+  // `null` if it happens before unmount. But there's no way for a callback react to know whether this update is happening
+  // during unmount or not, because we are trying to still be cross-compatible with React 18. Once we only need to support
+  // React 19, this can be corrected using a cleanup callback in our own combined ref.
+  if (value === null && cleanupRef.current) return
+
+  if (typeof ref === 'function') {
+    const cleanup = ref(value)
+    cleanupRef.current = cleanup || undefined
+  } else if (ref) {
+    // `React.Ref` is typed as immutable to protect consumers but it's OK to mutate it here. We could just change the
+    // type to only accept mutable refs, but then it would be harder to accept refs as props in React 19 because we
+    // would have to use the `React.ForwardedRef` type instead of `React.Ref`
+    ;(ref as MutableRefObject<T>).current = value
+  }
+}

From 0e14a427260ddaa45a1b6d65c733fdc63bbece7c Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 22:04:30 +0000
Subject: [PATCH 05/15] Revert accidental change

---
 packages/react/src/hooks/useRefObjectAsForwardedRef.ts | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
index 6d632b227b8..01051ed649f 100644
--- a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
+++ b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
@@ -1,7 +1,5 @@
 import type {ForwardedRef, RefObject} from 'react'
-import {useImperativeHandle, useMemo} from 'react'
-
-const unset = Symbol()
+import {useImperativeHandle} from 'react'
 
 /**
  * Use a ref object as the imperative handle for a forwarded ref. This can be used to

From f71d633692db0b0ef232208c374bf482d6b61a28 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 22:06:42 +0000
Subject: [PATCH 06/15] Fix typo

---
 packages/react/src/hooks/useCombinedRefs.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
index b36f3144e25..07059bd38df 100644
--- a/packages/react/src/hooks/useCombinedRefs.ts
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -26,7 +26,7 @@ import {useCallback, useEffect, useRef} from 'react'
  * // React 19
  * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
  *  const ref = useRef<HTMLButtonElement>(null)
- *  const combinedRef = useCombinedRefs(forwardedRef, ref)
+ *  const combinedRef = useCombinedRefs(externalRef, ref)
  *
  *  return <button ref={combinedRef} />
  * }

From 7a905ab039fe0364d91b6a49b8978d107935d7e2 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 22:08:11 +0000
Subject: [PATCH 07/15] Edit comment

---
 packages/react/src/hooks/useCombinedRefs.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
index 07059bd38df..233279156b6 100644
--- a/packages/react/src/hooks/useCombinedRefs.ts
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -78,9 +78,9 @@ type Ref<T> = ForwardedRef<T> | React19RefCallback<T> | StandardRef<T> | undefin
 
 function setRef<T>(ref: Ref<T>, value: T, cleanupRef: MutableRefObject<CleanupFunction | undefined>) {
   // NOTE: This is technically incorrect; in React 19 even with a callback ref it should be possible to call a ref with
-  // `null` if it happens before unmount. But there's no way for a callback react to know whether this update is happening
-  // during unmount or not, because we are trying to still be cross-compatible with React 18. Once we only need to support
-  // React 19, this can be corrected using a cleanup callback in our own combined ref.
+  // `null` if it happens before unmount. But there's no way for a React 18 ref to know whether this update is happening
+  // during unmount or not. Once we only need to support React 19, this can be corrected using a cleanup callback in
+  // our own combined ref.
   if (value === null && cleanupRef.current) return
 
   if (typeof ref === 'function') {

From 9361cd52224c429c7696f5fdcbd7c7ee4e927a02 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 22:12:18 +0000
Subject: [PATCH 08/15] Remove unecessary variable assignment

---
 packages/react/src/hooks/useCombinedRefs.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
index 233279156b6..40b2a0f4e55 100644
--- a/packages/react/src/hooks/useCombinedRefs.ts
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -84,8 +84,7 @@ function setRef<T>(ref: Ref<T>, value: T, cleanupRef: MutableRefObject<CleanupFu
   if (value === null && cleanupRef.current) return
 
   if (typeof ref === 'function') {
-    const cleanup = ref(value)
-    cleanupRef.current = cleanup || undefined
+    cleanupRef.current = ref(value) || undefined
   } else if (ref) {
     // `React.Ref` is typed as immutable to protect consumers but it's OK to mutate it here. We could just change the
     // type to only accept mutable refs, but then it would be harder to accept refs as props in React 19 because we

From c53642d41f72c809da99bd4e345eb46803d123e9 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Fri, 6 Mar 2026 22:24:01 +0000
Subject: [PATCH 09/15] Fix docs json

---
 packages/react/src/hooks/useCombinedRefs.hookDocs.json | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/hooks/useCombinedRefs.hookDocs.json b/packages/react/src/hooks/useCombinedRefs.hookDocs.json
index efbf596c897..0ac0dd319c0 100644
--- a/packages/react/src/hooks/useCombinedRefs.hookDocs.json
+++ b/packages/react/src/hooks/useCombinedRefs.hookDocs.json
@@ -5,16 +5,18 @@
   "parameters": [
     {
       "name": "refA",
-      "derive": true,
+      "type": "Ref<T>",
+      "required": true,
       "description": "First ref to combine."
     },
     {
       "name": "refB",
-      "derive": true,
+      "type": "Ref<T>",
+      "required": true,
       "description": "Second ref to combine."
     }
   ],
   "returns": {
-    "derive": true
+    "type": "RefCallback<T>"
   }
 }

From 1079845bedd36ca7ffed849e5b685c8bf5eac8c1 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 13:47:09 +0000
Subject: [PATCH 10/15] Migrate usage for `ButtonBase`, `Dialog`, `Heading`

---
 packages/react/src/Button/ButtonBase.tsx          | 5 ++---
 packages/react/src/Dialog/Dialog.tsx              | 4 ++--
 packages/react/src/Heading/Heading.tsx            | 4 ++--
 packages/react/src/deprecated/DialogV1/Dialog.tsx | 4 ++--
 4 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/packages/react/src/Button/ButtonBase.tsx b/packages/react/src/Button/ButtonBase.tsx
index ceaad3f39a8..4069647a934 100644
--- a/packages/react/src/Button/ButtonBase.tsx
+++ b/packages/react/src/Button/ButtonBase.tsx
@@ -51,7 +51,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
   } = props
 
   const innerRef = React.useRef<HTMLButtonElement>(null)
-  useCombinedRefs(forwardedRef, innerRef)
+  const combinedRefs = useCombinedRefs(forwardedRef, innerRef)
 
   const uuid = useId(id)
   const loadingAnnouncementID = `${uuid}-loading-announcement`
@@ -87,8 +87,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
       <Component
         aria-disabled={loading ? true : undefined}
         {...rest}
-        // @ts-ignore temporary disable as we migrate to css modules, until we remove PolymorphicForwardRefComponent
-        ref={innerRef}
+        ref={combinedRefs}
         className={clsx(classes.ButtonBase, className)}
         data-block={block ? 'block' : null}
         data-inactive={inactive ? true : undefined}
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
index ee72b754d33..ebf9d198d79 100644
--- a/packages/react/src/Dialog/Dialog.tsx
+++ b/packages/react/src/Dialog/Dialog.tsx
@@ -288,7 +288,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
   })
 
   const dialogRef = useRef<HTMLDivElement>(null)
-  useCombinedRefs(forwardedRef, dialogRef)
+  const combinedRef = useCombinedRefs(forwardedRef, dialogRef)
   const backdropRef = useRef<HTMLDivElement>(null)
 
   useFocusTrap({
@@ -361,7 +361,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
           }}
         >
           <div
-            ref={dialogRef}
+            ref={combinedRef}
             role={role}
             aria-labelledby={dialogLabelId}
             aria-describedby={dialogDescriptionId}
diff --git a/packages/react/src/Heading/Heading.tsx b/packages/react/src/Heading/Heading.tsx
index a7af94443d6..d913722cc63 100644
--- a/packages/react/src/Heading/Heading.tsx
+++ b/packages/react/src/Heading/Heading.tsx
@@ -14,7 +14,7 @@ type StyledHeadingProps = {
 
 const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
-  useCombinedRefs(forwardedRef, innerRef)
+  const combinedRef = useCombinedRefs(forwardedRef, innerRef)
 
   if (__DEV__) {
     /**
@@ -32,7 +32,7 @@ const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}
     }, [innerRef])
   }
 
-  return <Component className={clsx(className, classes.Heading)} data-variant={variant} {...props} ref={innerRef} />
+  return <Component className={clsx(className, classes.Heading)} data-variant={variant} {...props} ref={combinedRef} />
 }) as PolymorphicForwardRefComponent<HeadingLevels, StyledHeadingProps>
 
 Heading.displayName = 'Heading'
diff --git a/packages/react/src/deprecated/DialogV1/Dialog.tsx b/packages/react/src/deprecated/DialogV1/Dialog.tsx
index 50497303fe2..c0f26868652 100644
--- a/packages/react/src/deprecated/DialogV1/Dialog.tsx
+++ b/packages/react/src/deprecated/DialogV1/Dialog.tsx
@@ -48,7 +48,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
   ) => {
     const overlayRef = useRef(null)
     const modalRef = useRef<HTMLDivElement>(null)
-    useCombinedRefs(forwardedRef, modalRef)
+    const combinedRef = useCombinedRefs(forwardedRef, modalRef)
     const closeButtonRef = useRef(null)
 
     const onCloseClick = () => {
@@ -73,7 +73,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
         <span className={classes.Overlay} ref={overlayRef} />
         <Component
           tabIndex={-1}
-          ref={modalRef}
+          ref={combinedRef}
           role="dialog"
           aria-modal="true"
           {...props}

From f6bc0e571f5225f92ae4ed9a33255f6132fafaf6 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 09:47:37 -0400
Subject: [PATCH 11/15] Fix typo in test name

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx b/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
index d6f1f52df2e..eeb96c5f91c 100644
--- a/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
+++ b/packages/react/src/hooks/__tests__/useCombinedRefs.test.tsx
@@ -16,7 +16,7 @@ const Component = forwardRef<HTMLInputElement & HTMLButtonElement, {asButton?: b
 describe('useCombinedRefs', () => {
   describe('combining a forwarded ref with an internal ref', () => {
     describe('object refs', () => {
-      it('fowards the ref to the underlying element', async () => {
+      it('forwards the ref to the underlying element', async () => {
         const ref: InputOrButtonRef = {current: null}
 
         render(<Component ref={ref} />)

From 3f60a77eab312f6e2bfe2be2b6c23a3f8cc0692b Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 13:54:02 +0000
Subject: [PATCH 12/15] Fix types to force refs to accept null

---
 packages/react/src/hooks/useCombinedRefs.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/hooks/useCombinedRefs.ts b/packages/react/src/hooks/useCombinedRefs.ts
index 40b2a0f4e55..adac0d1fddf 100644
--- a/packages/react/src/hooks/useCombinedRefs.ts
+++ b/packages/react/src/hooks/useCombinedRefs.ts
@@ -31,7 +31,7 @@ import {useCallback, useEffect, useRef} from 'react'
  *  return <button ref={combinedRef} />
  * }
  */
-export function useCombinedRefs<T>(refA: Ref<T>, refB: Ref<T>) {
+export function useCombinedRefs<T>(refA: Ref<T | null>, refB: Ref<T | null>) {
   const cleanupARef = useRef<CleanupFunction>()
   const cleanupBRef = useRef<CleanupFunction>()
 

From 29fbb1ff5bbb23902c593949f496d5635d39a74a Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 14:48:49 +0000
Subject: [PATCH 13/15] Update exports snapshot

---
 packages/react/src/__tests__/__snapshots__/exports.test.ts.snap | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
index 6082f2ed77a..03dbeef3779 100644
--- a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -211,6 +211,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "type UnderlineNavProps",
   "useAnchoredPosition",
   "useColorSchemeVar",
+  "useCombinedRefs",
   "useConfirm",
   "useDetails",
   "useFocusTrap",
@@ -224,7 +225,6 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useOverlay",
   "useProvidedRefOrCreate",
   "useRefObjectAsForwardedRef",
-  "useCombinedRefs",
   "useResizeObserver",
   "useResponsiveValue",
   "useSafeTimeout",

From ece5160d694a8826f203e2445871469f08befd7c Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 14:50:25 +0000
Subject: [PATCH 14/15] Fix test

---
 packages/react/src/Autocomplete/Autocomplete.test.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/react/src/Autocomplete/Autocomplete.test.tsx b/packages/react/src/Autocomplete/Autocomplete.test.tsx
index 971b7b83ee8..eb8f603ad30 100644
--- a/packages/react/src/Autocomplete/Autocomplete.test.tsx
+++ b/packages/react/src/Autocomplete/Autocomplete.test.tsx
@@ -150,6 +150,7 @@ describe('Autocomplete', () => {
       const inputNode = getByLabelText(AUTOCOMPLETE_LABEL)
 
       expect(inputNode.getAttribute('aria-expanded')).not.toBe('true')
+      inputNode.focus()
       fireEvent.click(inputNode)
       fireEvent.keyDown(inputNode, {key: 'ArrowDown'})
 

From bdb0e39d56bfb13ab3e321622402369251cc3207 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Tue, 10 Mar 2026 10:45:19 -0400
Subject: [PATCH 15/15] Add `useCombinedRefs` hook, deprecate
 `useRefObjectAsForwardedRef` (#7645)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: iansan5653 <2294248+iansan5653@users.noreply.github.com>
---
 .changeset/combined-refs-hook.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/combined-refs-hook.md

diff --git a/.changeset/combined-refs-hook.md b/.changeset/combined-refs-hook.md
new file mode 100644
index 00000000000..75836b99950
--- /dev/null
+++ b/.changeset/combined-refs-hook.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Add `useCombinedRefs` hook and deprecate `useRefObjectAsForwardedRef`