From dcae302ce2aadca345f0704111535e0d71440fdb Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 16:26:29 +0000
Subject: [PATCH 01/18] Expose `useMergedRefs` and make ready for React 19

---
 .../__snapshots__/exports.test.ts.snap        |  1 +
 packages/react/src/hooks/index.ts             |  1 +
 .../src/hooks/useMergedRefs.hookDocs.json     | 22 +++++
 packages/react/src/hooks/useMergedRefs.ts     | 85 +++++++++++++++++++
 packages/react/src/index.ts                   |  1 +
 .../react/src/internal/hooks/useMergedRefs.ts | 16 ----
 6 files changed, 110 insertions(+), 16 deletions(-)
 create mode 100644 packages/react/src/hooks/useMergedRefs.hookDocs.json
 create mode 100644 packages/react/src/hooks/useMergedRefs.ts
 delete mode 100644 packages/react/src/internal/hooks/useMergedRefs.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..cec11bdd137 100644
--- a/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
+++ b/packages/react/src/__tests__/__snapshots__/exports.test.ts.snap
@@ -218,6 +218,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "useFormControlForwardedProps",
   "useId",
   "useIsomorphicLayoutEffect",
+  "useMergedRefs",
   "useOnEscapePress",
   "useOnOutsideClick",
   "useOpenAndCloseFocus",
diff --git a/packages/react/src/hooks/index.ts b/packages/react/src/hooks/index.ts
index d8259f5fd96..5938cacc2c0 100644
--- a/packages/react/src/hooks/index.ts
+++ b/packages/react/src/hooks/index.ts
@@ -16,3 +16,4 @@ export {useMnemonics} from './useMnemonics'
 export {useRefObjectAsForwardedRef} from './useRefObjectAsForwardedRef'
 export {useId} from './useId'
 export {useIsMacOS} from './useIsMacOS'
+export {useMergedRefs} from './useMergedRefs'
diff --git a/packages/react/src/hooks/useMergedRefs.hookDocs.json b/packages/react/src/hooks/useMergedRefs.hookDocs.json
new file mode 100644
index 00000000000..840bfa50598
--- /dev/null
+++ b/packages/react/src/hooks/useMergedRefs.hookDocs.json
@@ -0,0 +1,22 @@
+{
+  "name": "useMergedRefs",
+  "importPath": "@primer/react",
+  "stories": [],
+  "parameters": [
+    {
+      "name": "refA",
+      "type": "Ref<T>",
+      "required": true,
+      "description": "First ref to combine."
+    },
+    {
+      "name": "refB",
+      "type": "Ref<T>",
+      "required": true,
+      "description": "Second ref to combine."
+    }
+  ],
+  "returns": {
+    "type": "RefCallback<T>"
+  }
+}
diff --git a/packages/react/src/hooks/useMergedRefs.ts b/packages/react/src/hooks/useMergedRefs.ts
new file mode 100644
index 00000000000..4b3ed9ab661
--- /dev/null
+++ b/packages/react/src/hooks/useMergedRefs.ts
@@ -0,0 +1,85 @@
+import type {ForwardedRef, Ref as StandardRef, MutableRefObject} from 'react'
+import {useCallback} from 'react'
+
+/**
+ * Combine two refs of matching type (typically an external or forwarded ref and an internal `useRef` object or
+ * callback ref).
+ *
+ * If you need to combine more than two refs (what are you doing?) just nest the hook:
+ * `useMergedRefs(refA, useMergedRefs(refB, refC))`
+ *
+ * @param refA First ref to merge. The order is not important.
+ * @param refB Second ref to merge. 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 = useMergedRefs(forwardedRef, ref)
+ *
+ *  return <button ref={combinedRef} />
+ * })
+ *
+ * @example
+ * // React 19
+ * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
+ *  const ref = useRef<HTMLButtonElement>(null)
+ *  const combinedRef = useMergedRefs(externalRef, ref)
+ *
+ *  return <button ref={combinedRef} />
+ * }
+ */
+export function useMergedRefs<T>(refA: Ref<T | null>, refB: Ref<T | null>) {
+  return useCallback(
+    (value: T | null) => {
+      const cleanupA = setRef(refA, value)
+      const cleanupB = setRef(refB, value)
+
+      // Only works in React 19. In React 18, the cleanup function will be ignored and the ref will get called with
+      // `null` which will be passed to each ref as expected.
+      return () => {
+        // For object refs and callback refs that don't return cleanups, we still need to pass `null` on cleanup
+        if (cleanupA) cleanupA()
+        else setRef(refA, null)
+
+        if (cleanupB) cleanupB()
+        else setRef(refB, null)
+      }
+    },
+    [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) {
+  if (typeof ref === 'function') {
+    return ref(value)
+  } 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
+  }
+}
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 66c8d438e12..81c0fae44ad 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 {useMergedRefs} from './hooks/useMergedRefs'
 export {useResizeObserver} from './hooks/useResizeObserver'
 export {useResponsiveValue, type ResponsiveValue} from './hooks/useResponsiveValue'
 export {default as useIsomorphicLayoutEffect} from './utils/useIsomorphicLayoutEffect'
diff --git a/packages/react/src/internal/hooks/useMergedRefs.ts b/packages/react/src/internal/hooks/useMergedRefs.ts
deleted file mode 100644
index 7c67f20fadc..00000000000
--- a/packages/react/src/internal/hooks/useMergedRefs.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import {useCallback} from 'react'
-
-export function useMergedRefs<T>(
-  ...refs: Array<React.MutableRefObject<T> | React.ForwardedRef<T> | React.RefCallback<T>>
-): React.RefCallback<T> {
-  return useCallback((instance: T) => {
-    for (const ref of refs) {
-      if (typeof ref === 'function') {
-        ref(instance)
-      } else if (ref) {
-        ref.current = instance
-      }
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, refs)
-}

From bb26a62166374a6cc4f0f9cade2742036e255ac0 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 16:26:37 +0000
Subject: [PATCH 02/18] Add unit tests for `useMergedRefs`

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

diff --git a/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
new file mode 100644
index 00000000000..329dd9e8908
--- /dev/null
+++ b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
@@ -0,0 +1,153 @@
+import {render, renderHook} from '@testing-library/react'
+import React, {forwardRef, type RefObject} from 'react'
+import {describe, expect, it, vi} from 'vitest'
+import {useMergedRefs} from '../useMergedRefs'
+
+type InputOrButtonRef = RefObject<HTMLInputElement & HTMLButtonElement>
+
+const Component = forwardRef<HTMLInputElement & HTMLButtonElement, {asButton?: boolean}>(({asButton}, forwardedRef) => {
+  const ref: InputOrButtonRef = React.useRef(null)
+
+  const combinedRef = useMergedRefs(forwardedRef, ref)
+
+  return asButton ? <button type="button" ref={combinedRef} /> : <input ref={combinedRef} />
+})
+
+describe('useMergedRefs', () => {
+  describe('combining a forwarded ref with an internal ref', () => {
+    describe('object refs', () => {
+      it('forwards 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(() => useMergedRefs(refA, refB))
+
+      combined.result.current('test')
+      expect(refA).toHaveBeenCalledExactlyOnceWith('test')
+      expect(refB).toHaveBeenCalledExactlyOnceWith('test')
+    })
+
+    it('handles React 18 null values correctly', () => {
+      const refA = vi.fn()
+      const refB = vi.fn()
+
+      const combined = renderHook(() => useMergedRefs(refA, refB))
+
+      combined.result.current('test')
+      expect(refA).toHaveBeenCalledWith('test')
+      expect(refB).toHaveBeenCalledWith('test')
+
+      // on React 18, cleanup fn will be ignored and ref will be called with null
+      combined.result.current(null)
+
+      expect(refA).toHaveBeenCalledWith(null)
+      expect(refB).toHaveBeenCalledWith(null)
+    })
+
+    it('handles React 19 cleanup functions correctly and independently', () => {
+      const refA = vi.fn()
+      const cleanupRefB = vi.fn()
+      const refB = vi.fn().mockReturnValue(cleanupRefB)
+
+      const combined = renderHook(() => useMergedRefs(refA, refB))
+
+      const cleanup = combined.result.current('test')
+      expect(refA).toHaveBeenCalledWith('test')
+      expect(refB).toHaveBeenCalledWith('test')
+
+      // React 19 will call cleanup function and not pass null
+      cleanup()
+
+      expect(refA).toHaveBeenCalledWith(null)
+      expect(refB).not.toHaveBeenCalledWith(null)
+      expect(cleanupRefB).toHaveBeenCalledOnce()
+    })
+  })
+})

From 3d854c97387f8674266b1f6884bb8b741d594242 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 16:28:15 +0000
Subject: [PATCH 03/18] Update import paths

---
 packages/react/src/Banner/Banner.tsx   | 2 +-
 packages/react/src/Details/Details.tsx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/Banner/Banner.tsx b/packages/react/src/Banner/Banner.tsx
index 3b5a2eecaaf..44db1cbd3fb 100644
--- a/packages/react/src/Banner/Banner.tsx
+++ b/packages/react/src/Banner/Banner.tsx
@@ -3,7 +3,7 @@ import React, {forwardRef, useEffect} from 'react'
 import {AlertIcon, InfoIcon, StopIcon, CheckCircleIcon, XIcon} from '@primer/octicons-react'
 import {Button, IconButton, type ButtonProps} from '../Button'
 import {VisuallyHidden} from '../VisuallyHidden'
-import {useMergedRefs} from '../internal/hooks/useMergedRefs'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {useId} from '../hooks/useId'
 import classes from './Banner.module.css'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
diff --git a/packages/react/src/Details/Details.tsx b/packages/react/src/Details/Details.tsx
index c9135b2db31..2d512c41dfe 100644
--- a/packages/react/src/Details/Details.tsx
+++ b/packages/react/src/Details/Details.tsx
@@ -2,7 +2,7 @@ import React, {useEffect, type ComponentPropsWithoutRef, type ReactElement} from
 import {warning} from '../utils/warning'
 import {clsx} from 'clsx'
 import classes from './Details.module.css'
-import {useMergedRefs} from '../internal/hooks/useMergedRefs'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 
 const Root = React.forwardRef<HTMLDetailsElement, DetailsProps>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

From 8e77831e0e8ddf81db5ce5fae96af7e062a37b41 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 16:28:39 +0000
Subject: [PATCH 04/18] Deprecate `useProvidedRefOrCreate` and
 `useRefObjectAsForwardedRef`

---
 packages/react/src/hooks/useProvidedRefOrCreate.ts   | 12 ++++++++++++
 .../react/src/hooks/useRefObjectAsForwardedRef.ts    | 12 ++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/packages/react/src/hooks/useProvidedRefOrCreate.ts b/packages/react/src/hooks/useProvidedRefOrCreate.ts
index bfd209cbde2..bec68d8dabd 100644
--- a/packages/react/src/hooks/useProvidedRefOrCreate.ts
+++ b/packages/react/src/hooks/useProvidedRefOrCreate.ts
@@ -7,6 +7,18 @@ import React from 'react'
  * This hook aims to encapsulate that logic, so the consumer doesn't need to be concerned with violating `rules-of-hooks`.
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
  * @type TRef The type of the RefObject which should be created.
+ *
+ * @deprecated This hook is incompatible with forwarded callback refs. Prefer `useMergedRefs` with an internally
+ * created ref instead.
+ *
+ * ```diff
+ * - const ref = useProvidedRefOrCreate(forwardedRef as RefObject<...>)
+ * + const ref = useRef(null)
+ * + const mergedRef = useMergedRefs(forwardedRef, ref)
+ *
+ * - return <div ref={ref} />
+ * + return <div ref={mergedRef} />
+ * ```
  */
 export function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef | null>): React.RefObject<TRef | null> {
   const createdRef = React.useRef<TRef>(null)
diff --git a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
index 11becf147d7..0067228a7c6 100644
--- a/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
+++ b/packages/react/src/hooks/useRefObjectAsForwardedRef.ts
@@ -7,6 +7,18 @@ import {useImperativeHandle} from 'react'
  * instance with `.current`.
  *
  * **NOTE**: The `refObject` should be passed to the underlying element, NOT the `forwardedRef`.
+ *
+ * @deprecated Migrate to `useMergedRefs`. It's safer, faster, and easier to use:
+ *
+ * ```diff
+ *   const ref = useRef(null)
+ *
+ * - useRefObjectAsForwardedRef(forwardedRef, ref)
+ * + const mergedRef = useMergedRefs(forwardedRef, ref)
+ *
+ * - return <div ref={ref} />
+ * + return <div ref={mergedRef} />
+ * ```
  */
 export function useRefObjectAsForwardedRef<T>(forwardedRef: ForwardedRef<T>, refObject: RefObject<T | null>): void {
   useImperativeHandle<T | null, T | null>(forwardedRef, () => refObject.current)

From 973f184c7ed18526c786404376c11f2df71f2e54 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 12:39:52 -0400
Subject: [PATCH 05/18] Add changeset

---
 .changeset/early-ravens-visit.md | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .changeset/early-ravens-visit.md

diff --git a/.changeset/early-ravens-visit.md b/.changeset/early-ravens-visit.md
new file mode 100644
index 00000000000..f9dc700a5d4
--- /dev/null
+++ b/.changeset/early-ravens-visit.md
@@ -0,0 +1,7 @@
+---
+"@primer/react": minor
+---
+
+- New: Exposes new `useMergedRefs` hook that can merge two refs into a single combined ref
+- Deprecates `useRefObjectAsForwardedRef`; see doc comment for migration instructions
+- Deprecates `useProvidedRefOrCreate`; see doc comment for migration instructions

From 63fca2891ed40d60e5d2c114520e6b99cd29002c Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 15:22:26 +0000
Subject: [PATCH 06/18] Deprecate `useProvidedRefOrCreate` and migrate
 everything except for hooks

---
 contributor-docs/behaviors.md                 |  4 +--
 packages/react/src/ActionList/List.tsx        | 10 +++---
 packages/react/src/ActionMenu/ActionMenu.tsx  | 12 ++++---
 .../src/AnchoredOverlay/AnchoredOverlay.tsx   | 34 ++++++-------------
 .../react/src/ButtonGroup/ButtonGroup.tsx     | 10 +++---
 packages/react/src/Checkbox/Checkbox.tsx      | 18 +++++++---
 packages/react/src/Dialog/Dialog.tsx          |  8 ++---
 .../FilteredActionList/FilteredActionList.tsx | 17 +++++-----
 packages/react/src/PageHeader/PageHeader.tsx  | 13 ++++---
 .../react/src/SelectPanel/SelectPanel.tsx     |  8 +++--
 packages/react/src/TextInput/TextInput.tsx    |  8 ++---
 packages/react/src/TooltipV2/Tooltip.tsx      | 12 +++----
 packages/react/src/deprecated/ActionMenu.tsx  |  9 ++---
 .../experimental/SelectPanel2/SelectPanel.tsx | 10 +++---
 packages/react/src/experimental/Tabs/Tabs.tsx | 11 +++---
 .../react/src/hooks/useAnchoredPosition.ts    |  2 +-
 packages/react/src/hooks/useFocusTrap.ts      |  4 ++-
 17 files changed, 97 insertions(+), 93 deletions(-)

diff --git a/contributor-docs/behaviors.md b/contributor-docs/behaviors.md
index 9d6995c2e70..d8a45bb428c 100644
--- a/contributor-docs/behaviors.md
+++ b/contributor-docs/behaviors.md
@@ -44,7 +44,7 @@ Generic behaviors provide functionality that is not specific to any single compo
 
 ### Examples
 
-- `useProvidedRefOrCreate`
+- `useCombinedRefs`
 - `usePosition`
 - `useClickAway`
 - `useTypeAhead`
@@ -123,7 +123,7 @@ There are no restrictions on return values of generic behavior hooks. In fact, s
 
 - Often, a behavior will need to act on a real DOM element.
 - In this case, the hook should return a ref as part of the returned props for that element. The ref will get spread onto the element, giving the ref access to it.
-- Whenever you need a ref, it must be accepted as an optional setting to the hook. The hook then uses the `useProvidedRefOrCreate` hook to resolve a usable ref. Remember to return the resulting ref from the hook.
+- Whenever you need a ref, it must be accepted as an optional setting to the hook.
 
 ## Testing behaviors
 
diff --git a/packages/react/src/ActionList/List.tsx b/packages/react/src/ActionList/List.tsx
index ee9213fcb50..fdf152b3fce 100644
--- a/packages/react/src/ActionList/List.tsx
+++ b/packages/react/src/ActionList/List.tsx
@@ -1,11 +1,11 @@
-import React, {type JSX} from 'react'
+import React, {useRef, type JSX} from 'react'
 import {fixedForwardRef} from '../utils/modern-polymorphic'
 import {ActionListContainerContext} from './ActionListContainerContext'
 import {useSlots} from '../hooks/useSlots'
 import {Heading} from './Heading'
 import {useId} from '../hooks/useId'
 import {ListContext, type ActionListProps} from './shared'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
@@ -41,7 +41,8 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
 
   const ariaLabelledBy = slots.heading ? (slots.heading.props.id ?? headingId) : listLabelledBy
   const listRole = role || listRoleFromContainer
-  const listRef = useProvidedRefOrCreate(forwardedRef as React.RefObject<HTMLUListElement>)
+  const listRef = useRef<HTMLElement>(null)
+  const combinedRef = useCombinedRefs(forwardedRef, listRef)
 
   let enableFocusZone = false
   if (enableFocusZoneFromContainer !== undefined) enableFocusZone = enableFocusZoneFromContainer
@@ -69,12 +70,11 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
   return (
     <ListContext.Provider value={listContextValue}>
       {slots.heading}
-      {/* @ts-expect-error ref needs a non nullable ref */}
       <Component
         className={clsx(classes.ActionList, className)}
         role={listRole}
         aria-labelledby={ariaLabelledBy}
-        ref={listRef}
+        ref={combinedRef}
         data-dividers={showDividers}
         data-variant={variant}
         {...restProps}
diff --git a/packages/react/src/ActionMenu/ActionMenu.tsx b/packages/react/src/ActionMenu/ActionMenu.tsx
index e501b117377..62cb5578cd0 100644
--- a/packages/react/src/ActionMenu/ActionMenu.tsx
+++ b/packages/react/src/ActionMenu/ActionMenu.tsx
@@ -1,9 +1,9 @@
-import React, {useCallback, useContext, useMemo, useEffect, useState} from 'react'
+import React, {useCallback, useContext, useMemo, useEffect, useState, useRef} from 'react'
 import {TriangleDownIcon, ChevronRightIcon} from '@primer/octicons-react'
 import type {AnchoredOverlayProps} from '../AnchoredOverlay'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import type {OverlayProps} from '../Overlay'
-import {useProvidedRefOrCreate, useProvidedStateOrCreate, useMenuKeyboardNavigation} from '../hooks'
+import {useProvidedStateOrCreate, useMenuKeyboardNavigation, useCombinedRefs} from '../hooks'
 import {Divider} from '../ActionList/Divider'
 import {ActionListContainerContext} from '../ActionList/ActionListContainerContext'
 import type {ButtonProps} from '../Button'
@@ -110,7 +110,9 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
   )
   const menuButtonChildId = React.isValidElement(menuButtonChild) ? menuButtonChild.props.id : undefined
 
-  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const anchorRef = useRef<HTMLElement>(null)
+  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
+
   const anchorId = useId(menuButtonChildId)
   let renderAnchor: AnchoredOverlayProps['renderAnchor'] = null
   // 🚨 Hack for good API!
@@ -130,7 +132,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
             anchorChildren,
             mergeAnchorHandlers({...anchorProps}, anchorChildren.props),
           )
-          return React.cloneElement(child, {children: triggerButton, ref: anchorRef})
+          return React.cloneElement(child, {children: triggerButton, ref: combinedRef})
         }
       }
       return null
@@ -149,7 +151,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
               mergeAnchorHandlers({...anchorProps}, tooltipTrigger.props),
             )
             const tooltip = React.cloneElement(anchorChildren, {children: tooltipTriggerEl})
-            return React.cloneElement(child, {children: tooltip, ref: anchorRef})
+            return React.cloneElement(child, {children: tooltip, ref: combinedRef})
           }
         }
       } else {
diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index f60070447b3..d9cfa87e089 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -1,12 +1,12 @@
 import type React from 'react'
-import {useCallback, useEffect, type JSX} from 'react'
+import {useCallback, useEffect, useRef, type JSX} from 'react'
 import type {OverlayProps} from '../Overlay'
 import Overlay from '../Overlay'
 import type {FocusTrapHookSettings} from '../hooks/useFocusTrap'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useFocusZone} from '../hooks/useFocusZone'
-import {useAnchoredPosition, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
+import {useAnchoredPosition, useCombinedRefs, useRenderForcingRef} from '../hooks'
 import {useId} from '../hooks/useId'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
 import {type ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -27,7 +27,7 @@ interface AnchoredOverlayPropsWithAnchor {
   /**
    * An override to the internal ref that will be spread on to the renderAnchor
    */
-  anchorRef?: React.RefObject<HTMLElement | null>
+  anchorRef?: React.Ref<HTMLElement | null>
 
   /**
    * An override to the internal id that will be spread on to the renderAnchor
@@ -46,7 +46,7 @@ interface AnchoredOverlayPropsWithoutAnchor {
    * An override to the internal renderAnchor ref that will be used to position the overlay.
    * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
    */
-  anchorRef: React.RefObject<HTMLElement | null>
+  anchorRef: React.Ref<HTMLElement | null>
   /**
    * An override to the internal id that will be spread on to the renderAnchor
    */
@@ -160,8 +160,12 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
   displayCloseButton = true,
   closeButtonProps = defaultCloseButtonProps,
 }) => {
-  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const anchorRef = useRef<HTMLElement>(null)
+  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
+
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
+  const combinedOverlayRef = useCombinedRefs(updateOverlayRef, overlayProps?.ref)
+
   const anchorId = useId(externalAnchorId)
 
   const onClickOutside = useCallback(() => onClose?.('click-outside'), [onClose])
@@ -235,7 +239,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
     <>
       {renderAnchor &&
         renderAnchor({
-          ref: anchorRef,
+          ref: combinedRef,
           id: anchorId,
           'aria-haspopup': 'true',
           'aria-expanded': open,
@@ -261,12 +265,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           preventOverflow={preventOverflow}
           data-component="AnchoredOverlay"
           {...overlayProps}
-          ref={node => {
-            if (overlayProps?.ref) {
-              assignRef(overlayProps.ref, node)
-            }
-            updateOverlayRef(node)
-          }}
+          ref={combinedOverlayRef}
         >
           {showXIcon ? (
             <div className={classes.ResponsiveCloseButtonContainer}>
@@ -293,15 +292,4 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
   )
 }
 
-function assignRef<T>(
-  ref: React.MutableRefObject<T | null> | ((instance: T | null) => void) | null | undefined,
-  value: T | null,
-) {
-  if (typeof ref === 'function') {
-    ref(value)
-  } else if (ref) {
-    ref.current = value
-  }
-}
-
 AnchoredOverlay.displayName = 'AnchoredOverlay'
diff --git a/packages/react/src/ButtonGroup/ButtonGroup.tsx b/packages/react/src/ButtonGroup/ButtonGroup.tsx
index eff345f616b..27cefdab038 100644
--- a/packages/react/src/ButtonGroup/ButtonGroup.tsx
+++ b/packages/react/src/ButtonGroup/ButtonGroup.tsx
@@ -1,8 +1,8 @@
-import React, {type PropsWithChildren} from 'react'
+import React, {useRef, type PropsWithChildren} from 'react'
 import classes from './ButtonGroup.module.css'
 import {clsx} from 'clsx'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 export type ButtonGroupProps = PropsWithChildren<{
@@ -17,7 +17,8 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
   forwardRef,
 ) {
   const buttons = React.Children.map(children, (child, index) => <div key={index}>{child}</div>)
-  const buttonRef = useProvidedRefOrCreate(forwardRef as React.RefObject<HTMLDivElement | null>)
+  const buttonRef = useRef<HTMLDivElement>(null)
+  const combinedRef = useCombinedRefs(buttonRef, forwardRef)
 
   useFocusZone({
     containerRef: buttonRef,
@@ -27,8 +28,7 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
   })
 
   return (
-    //@ts-expect-error it needs a non nullable ref
-    <BaseComponent ref={buttonRef} className={clsx(className, classes.ButtonGroup)} role={role} {...rest}>
+    <BaseComponent ref={combinedRef} className={clsx(className, classes.ButtonGroup)} role={role} {...rest}>
       {buttons}
     </BaseComponent>
   )
diff --git a/packages/react/src/Checkbox/Checkbox.tsx b/packages/react/src/Checkbox/Checkbox.tsx
index c992f840ebb..48294ed72e4 100644
--- a/packages/react/src/Checkbox/Checkbox.tsx
+++ b/packages/react/src/Checkbox/Checkbox.tsx
@@ -1,6 +1,13 @@
 import {clsx} from 'clsx'
-import {useProvidedRefOrCreate} from '../hooks'
-import React, {useContext, useEffect, type ChangeEventHandler, type InputHTMLAttributes, type ReactElement} from 'react'
+import {useCombinedRefs} from '../hooks'
+import React, {
+  useContext,
+  useEffect,
+  useRef,
+  type ChangeEventHandler,
+  type InputHTMLAttributes,
+  type ReactElement,
+} from 'react'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 import type {FormValidationStatus} from '../utils/types/FormValidationStatus'
 import {CheckboxGroupContext} from '../CheckboxGroup/CheckboxGroupContext'
@@ -45,7 +52,8 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     ref,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
-    const checkboxRef = useProvidedRefOrCreate(ref as React.RefObject<HTMLInputElement>)
+    const checkboxRef = useRef<HTMLInputElement>(null)
+    const combinedRef = useCombinedRefs(checkboxRef, ref as React.RefObject<HTMLInputElement>)
     const checkboxGroupContext = useContext(CheckboxGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
@@ -54,7 +62,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     const inputProps = {
       type: 'checkbox',
       disabled,
-      ref: checkboxRef,
+      ref: combinedRef,
       checked: indeterminate ? false : checked,
       defaultChecked,
       required,
@@ -84,7 +92,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
         checkbox.setAttribute('aria-checked', checkbox.checked ? 'true' : 'false')
       }
     })
-    // @ts-expect-error inputProp needs a non nullable ref
+
     return <input {...inputProps} className={clsx(className, sharedClasses.Input, classes.Checkbox)} />
   },
 )
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
index 4ef73390514..8fa272a0b02 100644
--- a/packages/react/src/Dialog/Dialog.tsx
+++ b/packages/react/src/Dialog/Dialog.tsx
@@ -1,7 +1,7 @@
 import React, {useCallback, useEffect, useRef, useState, type SyntheticEvent} from 'react'
 import type {ButtonProps} from '../Button'
 import {Button, IconButton} from '../Button'
-import {useOnEscapePress, useProvidedRefOrCreate} from '../hooks'
+import {useOnEscapePress} from '../hooks'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
@@ -428,7 +428,8 @@ const Footer = React.forwardRef<HTMLDivElement, StyledFooterProps>(function Foot
 Footer.displayName = 'Dialog.Footer'
 
 const Buttons: React.FC<React.PropsWithChildren<{buttons: DialogButtonProps[]}>> = ({buttons}) => {
-  const autoFocusRef = useProvidedRefOrCreate<HTMLButtonElement>(buttons.find(button => button.autoFocus)?.ref)
+  const autoFocusRef = useRef<HTMLButtonElement>(null)
+  const combinedRef = useCombinedRefs(autoFocusRef, buttons.find(button => button.autoFocus)?.ref)
   let autoFocusCount = 0
   const [hasRendered, setHasRendered] = useState(0)
   useEffect(() => {
@@ -450,8 +451,7 @@ const Buttons: React.FC<React.PropsWithChildren<{buttons: DialogButtonProps[]}>>
             {...buttonProps}
             // 'normal' value is equivalent to 'default', this is used for backwards compatibility
             variant={buttonType === 'normal' ? 'default' : buttonType}
-            // @ts-expect-error it needs a non nullable ref
-            ref={autoFocus && autoFocusCount === 0 ? (autoFocusCount++, autoFocusRef) : null}
+            ref={autoFocus && autoFocusCount === 0 ? (autoFocusCount++, combinedRef) : null}
           >
             {content}
           </Button>
diff --git a/packages/react/src/FilteredActionList/FilteredActionList.tsx b/packages/react/src/FilteredActionList/FilteredActionList.tsx
index 10afa57107c..30955fdde78 100644
--- a/packages/react/src/FilteredActionList/FilteredActionList.tsx
+++ b/packages/react/src/FilteredActionList/FilteredActionList.tsx
@@ -9,7 +9,6 @@ import {ActionList, type ActionListProps} from '../ActionList'
 import type {GroupedListProps, ListPropsBase, ItemInput, RenderItemFn} from './'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
-import {useProvidedRefOrCreate} from '../hooks/useProvidedRefOrCreate'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import useScrollFlash from '../hooks/useScrollFlash'
 import {VisuallyHidden} from '../VisuallyHidden'
@@ -22,6 +21,7 @@ import {isValidElementType} from 'react-is'
 import {useAnnouncements} from './useAnnouncements'
 import {clsx} from 'clsx'
 import {useVirtualizer} from '@tanstack/react-virtual'
+import {useCombinedRefs} from '../hooks'
 
 const menuScrollMargins: ScrollIntoViewOptions = {startMargin: 0, endMargin: 8}
 
@@ -189,10 +189,11 @@ export function FilteredActionList({
   const inputAndListContainerRef = useRef<HTMLDivElement>(null)
   const listRef = useRef<HTMLUListElement>(null)
 
-  const scrollContainerRef = useProvidedRefOrCreate<HTMLDivElement>(
-    providedScrollContainerRef as React.RefObject<HTMLDivElement>,
-  )
-  const inputRef = useProvidedRefOrCreate<HTMLInputElement>(providedInputRef)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+  const combinedScrollContainerRef = useCombinedRefs(scrollContainerRef, providedScrollContainerRef)
+
+  const inputRef = useRef<HTMLInputElement>(null)
+  const combinedInputRef = useCombinedRefs(inputRef, providedInputRef)
 
   const usingRovingTabindex = _PrivateFocusManagement === 'roving-tabindex'
   const [listContainerElement, setListContainerElement] = useState<HTMLUListElement | null>(null)
@@ -548,8 +549,7 @@ export function FilteredActionList({
     <div ref={inputAndListContainerRef} className={clsx(className, classes.Root)} data-testid="filtered-action-list">
       <div className={classes.Header}>
         <TextInput
-          // @ts-expect-error it needs a non nullable ref
-          ref={inputRef}
+          ref={combinedInputRef}
           block
           width="auto"
           color="fg.default"
@@ -585,8 +585,7 @@ export function FilteredActionList({
           </label>
         </div>
       )}
-      {/* @ts-expect-error div needs a non nullable ref */}
-      <div ref={scrollContainerRef} className={classes.Container}>
+      <div ref={combinedScrollContainerRef} className={classes.Container}>
         {getBodyContent()}
       </div>
     </div>
diff --git a/packages/react/src/PageHeader/PageHeader.tsx b/packages/react/src/PageHeader/PageHeader.tsx
index 1acaadf06f3..2853b132ef1 100644
--- a/packages/react/src/PageHeader/PageHeader.tsx
+++ b/packages/react/src/PageHeader/PageHeader.tsx
@@ -1,4 +1,4 @@
-import React, {useEffect} from 'react'
+import React, {useEffect, useRef} from 'react'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
 import {isResponsiveValue} from '../hooks/useResponsiveValue'
 import Heading from '../Heading'
@@ -10,7 +10,7 @@ import {getResponsiveAttributes} from '../internal/utils/getResponsiveAttributes
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {areAllValuesTheSame, haveRegularAndWideSameValue} from '../utils/getBreakpointDeclarations'
 import {warning} from '../utils/warning'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import type {AriaRole, FCWithSlotMarker} from '../utils/types'
 import {clsx} from 'clsx'
 
@@ -49,7 +49,8 @@ export type PageHeaderProps = {
 
 const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeaderProps>>(
   ({children, className, as: BaseComponent = 'div', 'aria-label': ariaLabel, role, hasBorder}, forwardedRef) => {
-    const rootRef = useProvidedRefOrCreate<HTMLDivElement>(forwardedRef as React.RefObject<HTMLDivElement>)
+    const rootRef = useRef<HTMLDivElement>(null)
+    const combinedRef = useCombinedRefs(rootRef, forwardedRef)
 
     const isInteractive = (element: HTMLElement) => {
       return (
@@ -105,7 +106,7 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
 
     return (
       <BaseComponent
-        ref={rootRef}
+        ref={combinedRef}
         className={clsx(classes.PageHeader, className)}
         data-has-border={hasBorder ? 'true' : undefined}
         aria-label={ariaLabel}
@@ -205,12 +206,10 @@ export type TitleAreaProps = {
 
 const TitleArea = React.forwardRef<HTMLDivElement, React.PropsWithChildren<TitleAreaProps>>(
   ({children, className, hidden = false, variant = 'medium'}, forwardedRef) => {
-    const titleAreaRef = useProvidedRefOrCreate<HTMLDivElement>(forwardedRef as React.RefObject<HTMLDivElement>)
     return (
       <div
         className={clsx(classes.TitleArea, className)}
-        // @ts-expect-error it needs a non nullable ref
-        ref={titleAreaRef}
+        ref={forwardedRef}
         data-component="TitleArea"
         {...getResponsiveAttributes('size-variant', variant)}
         {...getHiddenDataAttributes(hidden)}
diff --git a/packages/react/src/SelectPanel/SelectPanel.tsx b/packages/react/src/SelectPanel/SelectPanel.tsx
index 82cd0812d1b..30ec8cf4fd7 100644
--- a/packages/react/src/SelectPanel/SelectPanel.tsx
+++ b/packages/react/src/SelectPanel/SelectPanel.tsx
@@ -12,7 +12,7 @@ import type {ItemProps, ItemInput} from './'
 import {SelectPanelMessage} from './SelectPanelMessage'
 
 import {Button, IconButton, LinkButton} from '../Button'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
@@ -513,7 +513,9 @@ function Panel({
     }
   }, [notice, open])
 
-  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const anchorRef = useRef<HTMLElement>(null)
+  const combinedAnchorRef = useCombinedRefs(anchorRef, externalAnchorRef)
+
   const onOpen: AnchoredOverlayProps['onOpen'] = useCallback(
     (gesture: Parameters<Exclude<AnchoredOverlayProps['onOpen'], undefined>>[0]) => onOpenChange(true, gesture),
     [onOpenChange],
@@ -860,7 +862,7 @@ function Panel({
     <>
       <AnchoredOverlay
         renderAnchor={renderMenuAnchor}
-        anchorRef={anchorRef}
+        anchorRef={combinedAnchorRef}
         align={align}
         open={open}
         onOpen={onOpen}
diff --git a/packages/react/src/TextInput/TextInput.tsx b/packages/react/src/TextInput/TextInput.tsx
index 88a4c716226..7c8585e7d73 100644
--- a/packages/react/src/TextInput/TextInput.tsx
+++ b/packages/react/src/TextInput/TextInput.tsx
@@ -7,7 +7,6 @@ import {AlertFillIcon} from '@primer/octicons-react'
 
 import classes from './TextInput.module.css'
 import TextInputInnerVisualSlot from '../internal/components/TextInputInnerVisualSlot'
-import {useProvidedRefOrCreate} from '../hooks'
 import type {Merge} from '../utils/types'
 import type {StyledWrapperProps} from '../internal/components/TextInputWrapper'
 import TextInputWrapper from '../internal/components/TextInputWrapper'
@@ -16,6 +15,7 @@ import UnstyledTextInput from '../internal/components/UnstyledTextInput'
 import VisuallyHidden from '../_VisuallyHidden'
 import {CharacterCounter} from '../utils/character-counter'
 import Text from '../Text'
+import {useCombinedRefs} from '../hooks'
 
 export type TextInputNonPassthroughProps = {
   /** @deprecated Use `leadingVisual` or `trailingVisual` prop instead */
@@ -103,7 +103,8 @@ const TextInput = React.forwardRef<HTMLInputElement, TextInputProps>(
     ref,
   ) => {
     const [isInputFocused, setIsInputFocused] = useState<boolean>(false)
-    const inputRef = useProvidedRefOrCreate(ref as React.RefObject<HTMLInputElement | null>)
+    const inputRef = useRef<HTMLInputElement>(null)
+    const combinedRef = useCombinedRefs(inputRef, ref)
     const [characterCount, setCharacterCount] = useState<string>('')
     const [isOverLimit, setIsOverLimit] = useState<boolean>(false)
     const [screenReaderMessage, setScreenReaderMessage] = useState<string>('')
@@ -258,8 +259,7 @@ const TextInput = React.forwardRef<HTMLInputElement, TextInputProps>(
             {typeof LeadingVisual !== 'string' && isValidElementType(LeadingVisual) ? <LeadingVisual /> : LeadingVisual}
           </TextInputInnerVisualSlot>
           <UnstyledTextInput
-            // @ts-expect-error it needs a non nullable ref
-            ref={inputRef}
+            ref={combinedRef}
             disabled={disabled}
             onFocus={handleInputFocus}
             onBlur={handleInputBlur}
diff --git a/packages/react/src/TooltipV2/Tooltip.tsx b/packages/react/src/TooltipV2/Tooltip.tsx
index bd33f49c562..a1bb824f566 100644
--- a/packages/react/src/TooltipV2/Tooltip.tsx
+++ b/packages/react/src/TooltipV2/Tooltip.tsx
@@ -1,5 +1,5 @@
-import React, {Children, useEffect, useRef, useState, useMemo, type ForwardRefExoticComponent} from 'react'
-import {useId, useProvidedRefOrCreate, useOnEscapePress, useIsMacOS} from '../hooks'
+import React, {Children, useEffect, useState, useMemo, type ForwardRefExoticComponent, useRef} from 'react'
+import {useId, useOnEscapePress, useIsMacOS, useCombinedRefs} from '../hooks'
 import {invariant} from '../utils/invariant'
 import {warning} from '../utils/warning'
 import {getAnchoredPosition} from '@primer/behaviors'
@@ -50,7 +50,7 @@ type TriggerPropsType = Pick<
   | 'onTouchCancel'
   | 'onTouchEnd'
 > & {
-  ref?: React.RefObject<HTMLElement>
+  ref?: React.Ref<HTMLElement>
 }
 
 // map tooltip direction to anchoredPosition props
@@ -124,7 +124,8 @@ export const Tooltip: ForwardRefExoticComponent<
   ) => {
     const tooltipId = useId(id)
     const child = Children.only(children)
-    const triggerRef = useProvidedRefOrCreate(forwardedRef as React.RefObject<HTMLElement>)
+    const triggerRef = useRef<HTMLElement>(null)
+    const combinedTriggerRef = useCombinedRefs(triggerRef, forwardedRef)
     const tooltipElRef = useRef<HTMLDivElement>(null)
 
     const [calculatedDirection, setCalculatedDirection] = useState<TooltipDirection>(direction)
@@ -279,8 +280,7 @@ export const Tooltip: ForwardRefExoticComponent<
           {React.isValidElement(child) &&
             // eslint-disable-next-line react-hooks/refs
             React.cloneElement(child as React.ReactElement<TriggerPropsType>, {
-              // @ts-expect-error it needs a non nullable ref
-              ref: triggerRef,
+              ref: combinedTriggerRef,
               // If it is a type description, we use tooltip to describe the trigger
               'aria-describedby': (() => {
                 // If tooltip is not a description type, keep the original aria-describedby
diff --git a/packages/react/src/deprecated/ActionMenu.tsx b/packages/react/src/deprecated/ActionMenu.tsx
index fa0cf1de949..5067ae6b28c 100644
--- a/packages/react/src/deprecated/ActionMenu.tsx
+++ b/packages/react/src/deprecated/ActionMenu.tsx
@@ -6,11 +6,11 @@ import {Divider} from './ActionList/Divider'
 import type {ButtonProps} from '../Button'
 import {Button} from '../Button'
 import type React from 'react'
-import {useCallback, useMemo, type JSX} from 'react'
+import {useCallback, useMemo, useRef, type JSX} from 'react'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import type {OverlayProps} from '../Overlay'
-import {useProvidedRefOrCreate} from '../hooks'
+import {useCombinedRefs} from '../hooks'
 import type {AnchoredOverlayWrapperAnchorProps} from '../AnchoredOverlay/AnchoredOverlay'
 
 interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
@@ -60,7 +60,8 @@ const ActionMenuBase = ({
   ...listProps
 }: ActionMenuProps): JSX.Element => {
   const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, setOpen, false)
-  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
+  const anchorRef = useRef<HTMLElement>(null)
+  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
   const onOpen = useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
   const onClose = useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
 
@@ -96,7 +97,7 @@ const ActionMenuBase = ({
   return (
     <AnchoredOverlay
       renderAnchor={renderMenuAnchor}
-      anchorRef={anchorRef}
+      anchorRef={combinedRef}
       open={combinedOpenState}
       onOpen={onOpen}
       onClose={onClose}
diff --git a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
index 3e61548d52b..fdce97d9f2d 100644
--- a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
+++ b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
@@ -1,4 +1,4 @@
-import React, {useEffect, useState, type MutableRefObject} from 'react'
+import React, {useEffect, useRef, useState, type MutableRefObject} from 'react'
 import {SearchIcon, XCircleFillIcon, XIcon, FilterRemoveIcon, AlertIcon, ArrowLeftIcon} from '@primer/octicons-react'
 
 import type {ButtonProps, TextInputProps, ActionListProps, LinkProps, CheckboxProps} from '../../index'
@@ -15,7 +15,7 @@ import {
 import Octicon from '../../Octicon'
 import {ActionListContainerContext} from '../../ActionList/ActionListContainerContext'
 import {useSlots} from '../../hooks/useSlots'
-import {useProvidedRefOrCreate, useId, useAnchoredPosition} from '../../hooks'
+import {useId, useAnchoredPosition, useCombinedRefs} from '../../hooks'
 import type {OverlayProps} from '../../Overlay/Overlay'
 import {BaseOverlay, heightMap} from '../../Overlay/Overlay'
 import {InputLabel} from '../../internal/components/InputLabel'
@@ -118,7 +118,9 @@ const Panel: React.FC<SelectPanelProps> = ({
   // with additional props for accessibility
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let Anchor: React.ReactElement<any> | undefined
-  const anchorRef = useProvidedRefOrCreate(providedAnchorRef)
+
+  const anchorRef = useRef<HTMLButtonElement>(null)
+  const combinedRef = useCombinedRefs(providedAnchorRef, anchorRef)
 
   const onAnchorClick = () => {
     if (!internalOpen) setInternalOpen(true)
@@ -130,7 +132,7 @@ const Panel: React.FC<SelectPanelProps> = ({
       // eslint-disable-next-line react-hooks/immutability
       Anchor = React.cloneElement(child, {
         // @ts-ignore TODO
-        ref: anchorRef,
+        ref: combinedRef,
         onClick: child.props.onClick || onAnchorClick,
         'aria-haspopup': true,
         'aria-expanded': internalOpen,
diff --git a/packages/react/src/experimental/Tabs/Tabs.tsx b/packages/react/src/experimental/Tabs/Tabs.tsx
index 69c891b5350..137d064fa5e 100644
--- a/packages/react/src/experimental/Tabs/Tabs.tsx
+++ b/packages/react/src/experimental/Tabs/Tabs.tsx
@@ -3,13 +3,14 @@ import React, {
   useContext,
   useId,
   useMemo,
+  useRef,
   type AriaAttributes,
   type ElementRef,
   type PropsWithChildren,
 } from 'react'
 import useIsomorphicLayoutEffect from '../../utils/useIsomorphicLayoutEffect'
 import {useControllableState} from '../../hooks/useControllableState'
-import {useProvidedRefOrCreate} from '../../hooks'
+import {useCombinedRefs} from '../../hooks'
 
 /**
  * Props to be used when the Tabs component's state is controlled by the parent
@@ -114,13 +115,14 @@ function useTabList<T extends HTMLElement>(
     'aria-orientation': AriaAttributes['aria-orientation']
     'aria-label': AriaAttributes['aria-label']
     'aria-labelledby': AriaAttributes['aria-labelledby']
-    ref: React.RefObject<T | null>
+    ref: React.Ref<T>
     role: 'tablist'
   }
 } {
   const {'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-orientation': ariaOrientation} = props
 
-  const ref = useProvidedRefOrCreate(props.ref)
+  const ref = useRef<T>(null)
+  const combinedRef = useCombinedRefs(ref, props.ref)
 
   const onKeyDown = (event: React.KeyboardEvent) => {
     const {current: tablist} = ref
@@ -172,7 +174,7 @@ function useTabList<T extends HTMLElement>(
 
   return {
     tabListProps: {
-      ref,
+      ref: combinedRef,
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledby,
       'aria-orientation': ariaOrientation ?? 'horizontal',
@@ -186,7 +188,6 @@ function TabList({children, ...rest}: TabListProps) {
   const {tabListProps} = useTabList<HTMLDivElement>(rest)
 
   return (
-    // @ts-expect-error it needs a non nullable ref
     <div {...rest} {...tabListProps}>
       {children}
     </div>
diff --git a/packages/react/src/hooks/useAnchoredPosition.ts b/packages/react/src/hooks/useAnchoredPosition.ts
index 32777aad1d7..b86e6f5ebdb 100644
--- a/packages/react/src/hooks/useAnchoredPosition.ts
+++ b/packages/react/src/hooks/useAnchoredPosition.ts
@@ -1,9 +1,9 @@
 import React from 'react'
 import {getAnchoredPosition} from '@primer/behaviors'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 import {useResizeObserver} from './useResizeObserver'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
+import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 
 export interface AnchoredPositionHookSettings extends Partial<PositionSettings> {
   floatingElementRef?: React.RefObject<Element | null>
diff --git a/packages/react/src/hooks/useFocusTrap.ts b/packages/react/src/hooks/useFocusTrap.ts
index 70b80072d51..ed09cb36f8b 100644
--- a/packages/react/src/hooks/useFocusTrap.ts
+++ b/packages/react/src/hooks/useFocusTrap.ts
@@ -1,7 +1,7 @@
 import React from 'react'
 import {focusTrap} from '@primer/behaviors'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 import {useOnOutsideClick} from './useOnOutsideClick'
+import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 
 export interface FocusTrapHookSettings {
   /**
@@ -53,8 +53,10 @@ export function useFocusTrap(
   dependencies: React.DependencyList = [],
 ): {containerRef: React.RefObject<HTMLElement | null>; initialFocusRef: React.RefObject<HTMLElement | null>} {
   const [outsideClicked, setOutsideClicked] = React.useState(false)
+
   const containerRef = useProvidedRefOrCreate(settings?.containerRef)
   const initialFocusRef = useProvidedRefOrCreate(settings?.initialFocusRef)
+
   const disabled = settings?.disabled
   const abortController = React.useRef<AbortController>()
   const previousFocusedElement = React.useRef<Element | null>(null)

From 3b478e3cbffb70d60b0155e69f985cacfe4050f0 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 15:31:10 +0000
Subject: [PATCH 07/18] Migrate `AnchoredOverlay` anchor ref

---
 packages/react/src/ActionMenu/ActionMenu.tsx | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/ActionMenu/ActionMenu.tsx b/packages/react/src/ActionMenu/ActionMenu.tsx
index 62cb5578cd0..3b2cefe8271 100644
--- a/packages/react/src/ActionMenu/ActionMenu.tsx
+++ b/packages/react/src/ActionMenu/ActionMenu.tsx
@@ -280,7 +280,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
   // we typecast anchorRef as required instead of optional
   // because we know that we're setting it in context in Menu
   const {
-    anchorRef,
+    anchorRef: contextAnchorRef,
     renderAnchor,
     anchorId,
     open,
@@ -289,6 +289,9 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
     isSubmenu = false,
   } = React.useContext(MenuContext) as MandateProps<MenuContextProps, 'anchorRef'>
 
+  const anchorRef = useRef<HTMLElement>(null)
+  const combinedAnchorRef = useCombinedRefs(anchorRef, contextAnchorRef)
+
   const containerRef = React.useRef<HTMLDivElement>(null)
   const isNarrow = useResponsiveValue({narrow: true}, false)
 
@@ -330,7 +333,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
 
   return (
     <AnchoredOverlay
-      anchorRef={anchorRef}
+      anchorRef={combinedAnchorRef}
       renderAnchor={renderAnchor}
       anchorId={anchorId}
       open={open}

From 04e1ca771270031995c82441b3fb434e3689d28f Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 15:46:41 +0000
Subject: [PATCH 08/18] Drop more ts-expect-error!

---
 packages/react/src/experimental/Tabs/Tabs.examples.stories.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/react/src/experimental/Tabs/Tabs.examples.stories.tsx b/packages/react/src/experimental/Tabs/Tabs.examples.stories.tsx
index ebe9a81a5aa..df2d7a518e4 100644
--- a/packages/react/src/experimental/Tabs/Tabs.examples.stories.tsx
+++ b/packages/react/src/experimental/Tabs/Tabs.examples.stories.tsx
@@ -17,7 +17,6 @@ const CustomTabList = (props: React.PropsWithChildren) => {
 
   return (
     <div style={{width: '200px'}}>
-      {/* @ts-expect-error it needs a non nullable ref */}
       <ActionList {...tabListProps}>{props.children}</ActionList>
     </div>
   )

From ec31af7839724fe47b001a359b2c4e399bf3402b Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Mon, 9 Mar 2026 15:47:07 +0000
Subject: [PATCH 09/18] Revert behaviors docs

---
 contributor-docs/behaviors.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/contributor-docs/behaviors.md b/contributor-docs/behaviors.md
index d8a45bb428c..9d6995c2e70 100644
--- a/contributor-docs/behaviors.md
+++ b/contributor-docs/behaviors.md
@@ -44,7 +44,7 @@ Generic behaviors provide functionality that is not specific to any single compo
 
 ### Examples
 
-- `useCombinedRefs`
+- `useProvidedRefOrCreate`
 - `usePosition`
 - `useClickAway`
 - `useTypeAhead`
@@ -123,7 +123,7 @@ There are no restrictions on return values of generic behavior hooks. In fact, s
 
 - Often, a behavior will need to act on a real DOM element.
 - In this case, the hook should return a ref as part of the returned props for that element. The ref will get spread onto the element, giving the ref access to it.
-- Whenever you need a ref, it must be accepted as an optional setting to the hook.
+- Whenever you need a ref, it must be accepted as an optional setting to the hook. The hook then uses the `useProvidedRefOrCreate` hook to resolve a usable ref. Remember to return the resulting ref from the hook.
 
 ## Testing behaviors
 

From 7bf1ce12b898d84242ba36aa97c25b1184e4eb4e Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 10 Mar 2026 12:32:50 -0400
Subject: [PATCH 10/18] Update packages/react/src/Checkbox/Checkbox.tsx

---
 packages/react/src/Checkbox/Checkbox.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/Checkbox/Checkbox.tsx b/packages/react/src/Checkbox/Checkbox.tsx
index 48294ed72e4..3bd7307b51b 100644
--- a/packages/react/src/Checkbox/Checkbox.tsx
+++ b/packages/react/src/Checkbox/Checkbox.tsx
@@ -53,7 +53,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
     const checkboxRef = useRef<HTMLInputElement>(null)
-    const combinedRef = useCombinedRefs(checkboxRef, ref as React.RefObject<HTMLInputElement>)
+    const combinedRef = useCombinedRefs(checkboxRef, ref)
     const checkboxGroupContext = useContext(CheckboxGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)

From 006cc27654a941d7f91de011873ec25cd49238dc Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 17 Mar 2026 17:00:55 +0000
Subject: [PATCH 11/18] Update useCombinedRefs to useMergedRefs

---
 packages/react/src/ActionList/List.tsx                    | 6 +++---
 packages/react/src/ActionMenu/ActionMenu.tsx              | 6 +++---
 packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx    | 6 +++---
 packages/react/src/ButtonGroup/ButtonGroup.tsx            | 6 +++---
 packages/react/src/Checkbox/Checkbox.tsx                  | 4 ++--
 packages/react/src/Dialog/Dialog.tsx                      | 2 +-
 .../react/src/FilteredActionList/FilteredActionList.tsx   | 6 +++---
 packages/react/src/PageHeader/PageHeader.tsx              | 6 +++---
 packages/react/src/SelectPanel/SelectPanel.tsx            | 4 ++--
 packages/react/src/TextInput/TextInput.tsx                | 6 +++---
 packages/react/src/TooltipV2/Tooltip.tsx                  | 4 ++--
 packages/react/src/deprecated/ActionMenu.tsx              | 6 +++---
 .../react/src/experimental/SelectPanel2/SelectPanel.tsx   | 4 ++--
 packages/react/src/experimental/Tabs/Tabs.tsx             | 4 ++--
 packages/react/src/hooks/__tests__/useMergedRefs.test.tsx | 4 ++--
 packages/react/src/hooks/useMergedRefs.ts                 | 8 ++++----
 16 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/packages/react/src/ActionList/List.tsx b/packages/react/src/ActionList/List.tsx
index fdf152b3fce..53cf3ede473 100644
--- a/packages/react/src/ActionList/List.tsx
+++ b/packages/react/src/ActionList/List.tsx
@@ -5,7 +5,7 @@ import {useSlots} from '../hooks/useSlots'
 import {Heading} from './Heading'
 import {useId} from '../hooks/useId'
 import {ListContext, type ActionListProps} from './shared'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
@@ -42,7 +42,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
   const ariaLabelledBy = slots.heading ? (slots.heading.props.id ?? headingId) : listLabelledBy
   const listRole = role || listRoleFromContainer
   const listRef = useRef<HTMLElement>(null)
-  const combinedRef = useCombinedRefs(forwardedRef, listRef)
+  const mergedRef = useMergedRefs(forwardedRef, listRef)
 
   let enableFocusZone = false
   if (enableFocusZoneFromContainer !== undefined) enableFocusZone = enableFocusZoneFromContainer
@@ -74,7 +74,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
         className={clsx(classes.ActionList, className)}
         role={listRole}
         aria-labelledby={ariaLabelledBy}
-        ref={combinedRef}
+        ref={mergedRef}
         data-dividers={showDividers}
         data-variant={variant}
         {...restProps}
diff --git a/packages/react/src/ActionMenu/ActionMenu.tsx b/packages/react/src/ActionMenu/ActionMenu.tsx
index 3b2cefe8271..0bf371af037 100644
--- a/packages/react/src/ActionMenu/ActionMenu.tsx
+++ b/packages/react/src/ActionMenu/ActionMenu.tsx
@@ -3,7 +3,7 @@ import {TriangleDownIcon, ChevronRightIcon} from '@primer/octicons-react'
 import type {AnchoredOverlayProps} from '../AnchoredOverlay'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import type {OverlayProps} from '../Overlay'
-import {useProvidedStateOrCreate, useMenuKeyboardNavigation, useCombinedRefs} from '../hooks'
+import {useProvidedStateOrCreate, useMenuKeyboardNavigation, useMergedRefs} from '../hooks'
 import {Divider} from '../ActionList/Divider'
 import {ActionListContainerContext} from '../ActionList/ActionListContainerContext'
 import type {ButtonProps} from '../Button'
@@ -111,7 +111,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
   const menuButtonChildId = React.isValidElement(menuButtonChild) ? menuButtonChild.props.id : undefined
 
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
+  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
 
   const anchorId = useId(menuButtonChildId)
   let renderAnchor: AnchoredOverlayProps['renderAnchor'] = null
@@ -290,7 +290,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
   } = React.useContext(MenuContext) as MandateProps<MenuContextProps, 'anchorRef'>
 
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedAnchorRef = useCombinedRefs(anchorRef, contextAnchorRef)
+  const combinedAnchorRef = useMergedRefs(anchorRef, contextAnchorRef)
 
   const containerRef = React.useRef<HTMLDivElement>(null)
   const isNarrow = useResponsiveValue({narrow: true}, false)
diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index d9cfa87e089..11a80529171 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -6,7 +6,7 @@ import type {FocusTrapHookSettings} from '../hooks/useFocusTrap'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useFocusZone} from '../hooks/useFocusZone'
-import {useAnchoredPosition, useCombinedRefs, useRenderForcingRef} from '../hooks'
+import {useAnchoredPosition, useMergedRefs, useRenderForcingRef} from '../hooks'
 import {useId} from '../hooks/useId'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
 import {type ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -161,10 +161,10 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
   closeButtonProps = defaultCloseButtonProps,
 }) => {
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
+  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
 
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
-  const combinedOverlayRef = useCombinedRefs(updateOverlayRef, overlayProps?.ref)
+  const combinedOverlayRef = useMergedRefs(updateOverlayRef, overlayProps?.ref)
 
   const anchorId = useId(externalAnchorId)
 
diff --git a/packages/react/src/ButtonGroup/ButtonGroup.tsx b/packages/react/src/ButtonGroup/ButtonGroup.tsx
index 27cefdab038..1dfe82dc0f4 100644
--- a/packages/react/src/ButtonGroup/ButtonGroup.tsx
+++ b/packages/react/src/ButtonGroup/ButtonGroup.tsx
@@ -2,7 +2,7 @@ import React, {useRef, type PropsWithChildren} from 'react'
 import classes from './ButtonGroup.module.css'
 import {clsx} from 'clsx'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 export type ButtonGroupProps = PropsWithChildren<{
@@ -18,7 +18,7 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
 ) {
   const buttons = React.Children.map(children, (child, index) => <div key={index}>{child}</div>)
   const buttonRef = useRef<HTMLDivElement>(null)
-  const combinedRef = useCombinedRefs(buttonRef, forwardRef)
+  const mergedRef = useMergedRefs(buttonRef, forwardRef)
 
   useFocusZone({
     containerRef: buttonRef,
@@ -28,7 +28,7 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
   })
 
   return (
-    <BaseComponent ref={combinedRef} className={clsx(className, classes.ButtonGroup)} role={role} {...rest}>
+    <BaseComponent ref={mergedRef} className={clsx(className, classes.ButtonGroup)} role={role} {...rest}>
       {buttons}
     </BaseComponent>
   )
diff --git a/packages/react/src/Checkbox/Checkbox.tsx b/packages/react/src/Checkbox/Checkbox.tsx
index 3bd7307b51b..8b0805b2def 100644
--- a/packages/react/src/Checkbox/Checkbox.tsx
+++ b/packages/react/src/Checkbox/Checkbox.tsx
@@ -1,5 +1,5 @@
 import {clsx} from 'clsx'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import React, {
   useContext,
   useEffect,
@@ -53,7 +53,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
     const checkboxRef = useRef<HTMLInputElement>(null)
-    const combinedRef = useCombinedRefs(checkboxRef, ref)
+    const mergedRef = useMergedRefs(checkboxRef, ref)
     const checkboxGroupContext = useContext(CheckboxGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
index 8fa272a0b02..81cd3b21b23 100644
--- a/packages/react/src/Dialog/Dialog.tsx
+++ b/packages/react/src/Dialog/Dialog.tsx
@@ -429,7 +429,7 @@ Footer.displayName = 'Dialog.Footer'
 
 const Buttons: React.FC<React.PropsWithChildren<{buttons: DialogButtonProps[]}>> = ({buttons}) => {
   const autoFocusRef = useRef<HTMLButtonElement>(null)
-  const combinedRef = useCombinedRefs(autoFocusRef, buttons.find(button => button.autoFocus)?.ref)
+  const mergedRef = useMergedRefs(autoFocusRef, buttons.find(button => button.autoFocus)?.ref)
   let autoFocusCount = 0
   const [hasRendered, setHasRendered] = useState(0)
   useEffect(() => {
diff --git a/packages/react/src/FilteredActionList/FilteredActionList.tsx b/packages/react/src/FilteredActionList/FilteredActionList.tsx
index 30955fdde78..94d4481599e 100644
--- a/packages/react/src/FilteredActionList/FilteredActionList.tsx
+++ b/packages/react/src/FilteredActionList/FilteredActionList.tsx
@@ -21,7 +21,7 @@ import {isValidElementType} from 'react-is'
 import {useAnnouncements} from './useAnnouncements'
 import {clsx} from 'clsx'
 import {useVirtualizer} from '@tanstack/react-virtual'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 
 const menuScrollMargins: ScrollIntoViewOptions = {startMargin: 0, endMargin: 8}
 
@@ -190,10 +190,10 @@ export function FilteredActionList({
   const listRef = useRef<HTMLUListElement>(null)
 
   const scrollContainerRef = useRef<HTMLDivElement>(null)
-  const combinedScrollContainerRef = useCombinedRefs(scrollContainerRef, providedScrollContainerRef)
+  const combinedScrollContainerRef = useMergedRefs(scrollContainerRef, providedScrollContainerRef)
 
   const inputRef = useRef<HTMLInputElement>(null)
-  const combinedInputRef = useCombinedRefs(inputRef, providedInputRef)
+  const combinedInputRef = useMergedRefs(inputRef, providedInputRef)
 
   const usingRovingTabindex = _PrivateFocusManagement === 'roving-tabindex'
   const [listContainerElement, setListContainerElement] = useState<HTMLUListElement | null>(null)
diff --git a/packages/react/src/PageHeader/PageHeader.tsx b/packages/react/src/PageHeader/PageHeader.tsx
index 2853b132ef1..fa3095f86aa 100644
--- a/packages/react/src/PageHeader/PageHeader.tsx
+++ b/packages/react/src/PageHeader/PageHeader.tsx
@@ -10,7 +10,7 @@ import {getResponsiveAttributes} from '../internal/utils/getResponsiveAttributes
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {areAllValuesTheSame, haveRegularAndWideSameValue} from '../utils/getBreakpointDeclarations'
 import {warning} from '../utils/warning'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {AriaRole, FCWithSlotMarker} from '../utils/types'
 import {clsx} from 'clsx'
 
@@ -50,7 +50,7 @@ export type PageHeaderProps = {
 const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeaderProps>>(
   ({children, className, as: BaseComponent = 'div', 'aria-label': ariaLabel, role, hasBorder}, forwardedRef) => {
     const rootRef = useRef<HTMLDivElement>(null)
-    const combinedRef = useCombinedRefs(rootRef, forwardedRef)
+    const mergedRef = useMergedRefs(rootRef, forwardedRef)
 
     const isInteractive = (element: HTMLElement) => {
       return (
@@ -106,7 +106,7 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
 
     return (
       <BaseComponent
-        ref={combinedRef}
+        ref={mergedRef}
         className={clsx(classes.PageHeader, className)}
         data-has-border={hasBorder ? 'true' : undefined}
         aria-label={ariaLabel}
diff --git a/packages/react/src/SelectPanel/SelectPanel.tsx b/packages/react/src/SelectPanel/SelectPanel.tsx
index 30ec8cf4fd7..d7dc81420a1 100644
--- a/packages/react/src/SelectPanel/SelectPanel.tsx
+++ b/packages/react/src/SelectPanel/SelectPanel.tsx
@@ -12,7 +12,7 @@ import type {ItemProps, ItemInput} from './'
 import {SelectPanelMessage} from './SelectPanelMessage'
 
 import {Button, IconButton, LinkButton} from '../Button'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
@@ -514,7 +514,7 @@ function Panel({
   }, [notice, open])
 
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedAnchorRef = useCombinedRefs(anchorRef, externalAnchorRef)
+  const combinedAnchorRef = useMergedRefs(anchorRef, externalAnchorRef)
 
   const onOpen: AnchoredOverlayProps['onOpen'] = useCallback(
     (gesture: Parameters<Exclude<AnchoredOverlayProps['onOpen'], undefined>>[0]) => onOpenChange(true, gesture),
diff --git a/packages/react/src/TextInput/TextInput.tsx b/packages/react/src/TextInput/TextInput.tsx
index 7c8585e7d73..eaba650e882 100644
--- a/packages/react/src/TextInput/TextInput.tsx
+++ b/packages/react/src/TextInput/TextInput.tsx
@@ -15,7 +15,7 @@ import UnstyledTextInput from '../internal/components/UnstyledTextInput'
 import VisuallyHidden from '../_VisuallyHidden'
 import {CharacterCounter} from '../utils/character-counter'
 import Text from '../Text'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 
 export type TextInputNonPassthroughProps = {
   /** @deprecated Use `leadingVisual` or `trailingVisual` prop instead */
@@ -104,7 +104,7 @@ const TextInput = React.forwardRef<HTMLInputElement, TextInputProps>(
   ) => {
     const [isInputFocused, setIsInputFocused] = useState<boolean>(false)
     const inputRef = useRef<HTMLInputElement>(null)
-    const combinedRef = useCombinedRefs(inputRef, ref)
+    const mergedRef = useMergedRefs(inputRef, ref)
     const [characterCount, setCharacterCount] = useState<string>('')
     const [isOverLimit, setIsOverLimit] = useState<boolean>(false)
     const [screenReaderMessage, setScreenReaderMessage] = useState<string>('')
@@ -259,7 +259,7 @@ const TextInput = React.forwardRef<HTMLInputElement, TextInputProps>(
             {typeof LeadingVisual !== 'string' && isValidElementType(LeadingVisual) ? <LeadingVisual /> : LeadingVisual}
           </TextInputInnerVisualSlot>
           <UnstyledTextInput
-            ref={combinedRef}
+            ref={mergedRef}
             disabled={disabled}
             onFocus={handleInputFocus}
             onBlur={handleInputBlur}
diff --git a/packages/react/src/TooltipV2/Tooltip.tsx b/packages/react/src/TooltipV2/Tooltip.tsx
index a1bb824f566..d0bac5e36c1 100644
--- a/packages/react/src/TooltipV2/Tooltip.tsx
+++ b/packages/react/src/TooltipV2/Tooltip.tsx
@@ -1,5 +1,5 @@
 import React, {Children, useEffect, useState, useMemo, type ForwardRefExoticComponent, useRef} from 'react'
-import {useId, useOnEscapePress, useIsMacOS, useCombinedRefs} from '../hooks'
+import {useId, useOnEscapePress, useIsMacOS, useMergedRefs} from '../hooks'
 import {invariant} from '../utils/invariant'
 import {warning} from '../utils/warning'
 import {getAnchoredPosition} from '@primer/behaviors'
@@ -125,7 +125,7 @@ export const Tooltip: ForwardRefExoticComponent<
     const tooltipId = useId(id)
     const child = Children.only(children)
     const triggerRef = useRef<HTMLElement>(null)
-    const combinedTriggerRef = useCombinedRefs(triggerRef, forwardedRef)
+    const combinedTriggerRef = useMergedRefs(triggerRef, forwardedRef)
     const tooltipElRef = useRef<HTMLDivElement>(null)
 
     const [calculatedDirection, setCalculatedDirection] = useState<TooltipDirection>(direction)
diff --git a/packages/react/src/deprecated/ActionMenu.tsx b/packages/react/src/deprecated/ActionMenu.tsx
index 5067ae6b28c..65343d1318b 100644
--- a/packages/react/src/deprecated/ActionMenu.tsx
+++ b/packages/react/src/deprecated/ActionMenu.tsx
@@ -10,7 +10,7 @@ import {useCallback, useMemo, useRef, type JSX} from 'react'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import type {OverlayProps} from '../Overlay'
-import {useCombinedRefs} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {AnchoredOverlayWrapperAnchorProps} from '../AnchoredOverlay/AnchoredOverlay'
 
 interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
@@ -61,7 +61,7 @@ const ActionMenuBase = ({
 }: ActionMenuProps): JSX.Element => {
   const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, setOpen, false)
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedRef = useCombinedRefs(anchorRef, externalAnchorRef)
+  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
   const onOpen = useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
   const onClose = useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
 
@@ -97,7 +97,7 @@ const ActionMenuBase = ({
   return (
     <AnchoredOverlay
       renderAnchor={renderMenuAnchor}
-      anchorRef={combinedRef}
+      anchorref={mergedRef}
       open={combinedOpenState}
       onOpen={onOpen}
       onClose={onClose}
diff --git a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
index fdce97d9f2d..e7bb7b8ffc7 100644
--- a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
+++ b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
@@ -15,7 +15,7 @@ import {
 import Octicon from '../../Octicon'
 import {ActionListContainerContext} from '../../ActionList/ActionListContainerContext'
 import {useSlots} from '../../hooks/useSlots'
-import {useId, useAnchoredPosition, useCombinedRefs} from '../../hooks'
+import {useId, useAnchoredPosition, useMergedRefs} from '../../hooks'
 import type {OverlayProps} from '../../Overlay/Overlay'
 import {BaseOverlay, heightMap} from '../../Overlay/Overlay'
 import {InputLabel} from '../../internal/components/InputLabel'
@@ -120,7 +120,7 @@ const Panel: React.FC<SelectPanelProps> = ({
   let Anchor: React.ReactElement<any> | undefined
 
   const anchorRef = useRef<HTMLButtonElement>(null)
-  const combinedRef = useCombinedRefs(providedAnchorRef, anchorRef)
+  const mergedRef = useMergedRefs(providedAnchorRef, anchorRef)
 
   const onAnchorClick = () => {
     if (!internalOpen) setInternalOpen(true)
diff --git a/packages/react/src/experimental/Tabs/Tabs.tsx b/packages/react/src/experimental/Tabs/Tabs.tsx
index 137d064fa5e..ad171ea4c41 100644
--- a/packages/react/src/experimental/Tabs/Tabs.tsx
+++ b/packages/react/src/experimental/Tabs/Tabs.tsx
@@ -10,7 +10,7 @@ import React, {
 } from 'react'
 import useIsomorphicLayoutEffect from '../../utils/useIsomorphicLayoutEffect'
 import {useControllableState} from '../../hooks/useControllableState'
-import {useCombinedRefs} from '../../hooks'
+import {useMergedRefs} from '../../hooks'
 
 /**
  * Props to be used when the Tabs component's state is controlled by the parent
@@ -122,7 +122,7 @@ function useTabList<T extends HTMLElement>(
   const {'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledby, 'aria-orientation': ariaOrientation} = props
 
   const ref = useRef<T>(null)
-  const combinedRef = useCombinedRefs(ref, props.ref)
+  const mergedRef = useMergedRefs(ref, props.ref)
 
   const onKeyDown = (event: React.KeyboardEvent) => {
     const {current: tablist} = ref
diff --git a/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
index 329dd9e8908..43ef7f8d706 100644
--- a/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
+++ b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
@@ -8,9 +8,9 @@ type InputOrButtonRef = RefObject<HTMLInputElement & HTMLButtonElement>
 const Component = forwardRef<HTMLInputElement & HTMLButtonElement, {asButton?: boolean}>(({asButton}, forwardedRef) => {
   const ref: InputOrButtonRef = React.useRef(null)
 
-  const combinedRef = useMergedRefs(forwardedRef, ref)
+  const mergedRef = useMergedRefs(forwardedRef, ref)
 
-  return asButton ? <button type="button" ref={combinedRef} /> : <input ref={combinedRef} />
+  return asButton ? <button type="button" ref={mergedRef} /> : <input ref={mergedRef} />
 })
 
 describe('useMergedRefs', () => {
diff --git a/packages/react/src/hooks/useMergedRefs.ts b/packages/react/src/hooks/useMergedRefs.ts
index 4b3ed9ab661..a80b63f8e72 100644
--- a/packages/react/src/hooks/useMergedRefs.ts
+++ b/packages/react/src/hooks/useMergedRefs.ts
@@ -17,18 +17,18 @@ import {useCallback} from 'react'
  * // React 18
  * const Example = forwardRef<HTMLButtonElement, {}>((props, forwardedRef) => {
  *  const ref = useRef<HTMLButtonElement>(null)
- *  const combinedRef = useMergedRefs(forwardedRef, ref)
+ *  const mergedRef = useMergedRefs(forwardedRef, ref)
  *
- *  return <button ref={combinedRef} />
+ *  return <button ref={mergedRef} />
  * })
  *
  * @example
  * // React 19
  * const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
  *  const ref = useRef<HTMLButtonElement>(null)
- *  const combinedRef = useMergedRefs(externalRef, ref)
+ *  const mergedRef = useMergedRefs(externalRef, ref)
  *
- *  return <button ref={combinedRef} />
+ *  return <button ref={mergedRef} />
  * }
  */
 export function useMergedRefs<T>(refA: Ref<T | null>, refB: Ref<T | null>) {

From 196c0834c34d1210ec6d9e77288107129b2ec253 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 18:51:37 +0000
Subject: [PATCH 12/18] Fix a few renames

---
 packages/react/src/ActionMenu/ActionMenu.tsx   | 4 ++--
 packages/react/src/SelectPanel/SelectPanel.tsx | 4 ++--
 packages/react/src/TooltipV2/Tooltip.tsx       | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/react/src/ActionMenu/ActionMenu.tsx b/packages/react/src/ActionMenu/ActionMenu.tsx
index 70218a53b5b..507eaaf4c25 100644
--- a/packages/react/src/ActionMenu/ActionMenu.tsx
+++ b/packages/react/src/ActionMenu/ActionMenu.tsx
@@ -300,7 +300,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
   } = React.useContext(MenuContext) as MandateProps<MenuContextProps, 'anchorRef'>
 
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedAnchorRef = useMergedRefs(anchorRef, contextAnchorRef)
+  const mergedAnchorRef = useMergedRefs(anchorRef, contextAnchorRef)
 
   const containerRef = React.useRef<HTMLDivElement>(null)
   const isNarrow = useResponsiveValue({narrow: true}, false)
@@ -345,7 +345,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
 
   return (
     <AnchoredOverlay
-      anchorRef={combinedAnchorRef}
+      anchorRef={mergedAnchorRef}
       renderAnchor={renderAnchor}
       anchorId={anchorId}
       open={open}
diff --git a/packages/react/src/SelectPanel/SelectPanel.tsx b/packages/react/src/SelectPanel/SelectPanel.tsx
index d7dc81420a1..061abb5c5d5 100644
--- a/packages/react/src/SelectPanel/SelectPanel.tsx
+++ b/packages/react/src/SelectPanel/SelectPanel.tsx
@@ -514,7 +514,7 @@ function Panel({
   }, [notice, open])
 
   const anchorRef = useRef<HTMLElement>(null)
-  const combinedAnchorRef = useMergedRefs(anchorRef, externalAnchorRef)
+  const mergedAnchorRef = useMergedRefs(anchorRef, externalAnchorRef)
 
   const onOpen: AnchoredOverlayProps['onOpen'] = useCallback(
     (gesture: Parameters<Exclude<AnchoredOverlayProps['onOpen'], undefined>>[0]) => onOpenChange(true, gesture),
@@ -862,7 +862,7 @@ function Panel({
     <>
       <AnchoredOverlay
         renderAnchor={renderMenuAnchor}
-        anchorRef={combinedAnchorRef}
+        anchorRef={mergedAnchorRef}
         align={align}
         open={open}
         onOpen={onOpen}
diff --git a/packages/react/src/TooltipV2/Tooltip.tsx b/packages/react/src/TooltipV2/Tooltip.tsx
index 4c61677e354..02ed05f12b4 100644
--- a/packages/react/src/TooltipV2/Tooltip.tsx
+++ b/packages/react/src/TooltipV2/Tooltip.tsx
@@ -127,7 +127,7 @@ export const Tooltip: ForwardRefExoticComponent<
     const tooltipId = useId(id)
     const child = Children.only(children)
     const triggerRef = useRef<HTMLElement>(null)
-    const combinedTriggerRef = useMergedRefs(triggerRef, forwardedRef)
+    const mergedTriggerRef = useMergedRefs(triggerRef, forwardedRef)
     const tooltipElRef = useRef<HTMLDivElement>(null)
 
     const [calculatedDirection, setCalculatedDirection] = useState<TooltipDirection>(direction)
@@ -285,7 +285,7 @@ export const Tooltip: ForwardRefExoticComponent<
           {React.isValidElement(child) &&
             // eslint-disable-next-line react-hooks/refs
             React.cloneElement(child as React.ReactElement<TriggerPropsType>, {
-              ref: combinedTriggerRef,
+              ref: mergedTriggerRef,
               // If it is a type description, we use tooltip to describe the trigger
               'aria-describedby': (() => {
                 // If tooltip is not a description type, keep the original aria-describedby

From 6e410b64f952b1170665d93660a875f9f03bb7e5 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 18:59:03 +0000
Subject: [PATCH 13/18] Somehow I missed some spots???

---
 packages/react/src/Checkbox/Checkbox.tsx                     | 2 +-
 packages/react/src/Dialog/Dialog.tsx                         | 4 ++--
 packages/react/src/experimental/SelectPanel2/SelectPanel.tsx | 3 +--
 packages/react/src/experimental/Tabs/Tabs.tsx                | 2 +-
 4 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/packages/react/src/Checkbox/Checkbox.tsx b/packages/react/src/Checkbox/Checkbox.tsx
index 8b0805b2def..54dcab5d091 100644
--- a/packages/react/src/Checkbox/Checkbox.tsx
+++ b/packages/react/src/Checkbox/Checkbox.tsx
@@ -62,7 +62,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     const inputProps = {
       type: 'checkbox',
       disabled,
-      ref: combinedRef,
+      ref: mergedRef,
       checked: indeterminate ? false : checked,
       defaultChecked,
       required,
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
index 81cd3b21b23..e2aff660c01 100644
--- a/packages/react/src/Dialog/Dialog.tsx
+++ b/packages/react/src/Dialog/Dialog.tsx
@@ -1,7 +1,7 @@
 import React, {useCallback, useEffect, useRef, useState, type SyntheticEvent} from 'react'
 import type {ButtonProps} from '../Button'
 import {Button, IconButton} from '../Button'
-import {useOnEscapePress} from '../hooks'
+import {useMergedRefs, useOnEscapePress} from '../hooks'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
@@ -451,7 +451,7 @@ const Buttons: React.FC<React.PropsWithChildren<{buttons: DialogButtonProps[]}>>
             {...buttonProps}
             // 'normal' value is equivalent to 'default', this is used for backwards compatibility
             variant={buttonType === 'normal' ? 'default' : buttonType}
-            ref={autoFocus && autoFocusCount === 0 ? (autoFocusCount++, combinedRef) : null}
+            ref={autoFocus && autoFocusCount === 0 ? (autoFocusCount++, mergedRef) : null}
           >
             {content}
           </Button>
diff --git a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
index e7bb7b8ffc7..05d0e3c98f7 100644
--- a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
+++ b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
@@ -131,8 +131,7 @@ const Panel: React.FC<SelectPanelProps> = ({
     if (React.isValidElement(child) && (child.type === SelectPanelButton || isSlot(child, SelectPanelButton))) {
       // eslint-disable-next-line react-hooks/immutability
       Anchor = React.cloneElement(child, {
-        // @ts-ignore TODO
-        ref: combinedRef,
+        ref: mergedRef,
         onClick: child.props.onClick || onAnchorClick,
         'aria-haspopup': true,
         'aria-expanded': internalOpen,
diff --git a/packages/react/src/experimental/Tabs/Tabs.tsx b/packages/react/src/experimental/Tabs/Tabs.tsx
index ad171ea4c41..50400ad435a 100644
--- a/packages/react/src/experimental/Tabs/Tabs.tsx
+++ b/packages/react/src/experimental/Tabs/Tabs.tsx
@@ -174,7 +174,7 @@ function useTabList<T extends HTMLElement>(
 
   return {
     tabListProps: {
-      ref: combinedRef,
+      ref: mergedRef,
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledby,
       'aria-orientation': ariaOrientation ?? 'horizontal',

From a09ae22994f4ce84e4c1e70f243b706c5d969283 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 19:01:37 +0000
Subject: [PATCH 14/18] anchorref > anchorRef

---
 packages/react/src/deprecated/ActionMenu.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/deprecated/ActionMenu.tsx b/packages/react/src/deprecated/ActionMenu.tsx
index 65343d1318b..43cf9371151 100644
--- a/packages/react/src/deprecated/ActionMenu.tsx
+++ b/packages/react/src/deprecated/ActionMenu.tsx
@@ -97,7 +97,7 @@ const ActionMenuBase = ({
   return (
     <AnchoredOverlay
       renderAnchor={renderMenuAnchor}
-      anchorref={mergedRef}
+      anchorRef={mergedRef}
       open={combinedOpenState}
       onOpen={onOpen}
       onClose={onClose}

From 90e9941157d1b576a87284cd6a6cdd4cd1423249 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 19:23:36 +0000
Subject: [PATCH 15/18] Revert some files because of a valid use case

---
 packages/react/src/ActionMenu/ActionMenu.tsx  | 19 +++++++------------
 .../src/AnchoredOverlay/AnchoredOverlay.tsx   | 13 +++++--------
 .../react/src/SelectPanel/SelectPanel.tsx     |  8 +++-----
 packages/react/src/deprecated/ActionMenu.tsx  |  9 ++++-----
 .../experimental/SelectPanel2/SelectPanel.tsx | 11 +++++------
 .../react/src/hooks/useAnchoredPosition.ts    |  2 +-
 packages/react/src/hooks/useFocusTrap.ts      |  4 +---
 7 files changed, 26 insertions(+), 40 deletions(-)

diff --git a/packages/react/src/ActionMenu/ActionMenu.tsx b/packages/react/src/ActionMenu/ActionMenu.tsx
index 507eaaf4c25..429d1a5d0b0 100644
--- a/packages/react/src/ActionMenu/ActionMenu.tsx
+++ b/packages/react/src/ActionMenu/ActionMenu.tsx
@@ -1,10 +1,10 @@
-import React, {useCallback, useContext, useMemo, useEffect, useState, useRef} from 'react'
+import React, {useCallback, useContext, useMemo, useEffect, useState} from 'react'
 import {clsx} from 'clsx'
 import {TriangleDownIcon, ChevronRightIcon} from '@primer/octicons-react'
 import type {AnchoredOverlayProps} from '../AnchoredOverlay'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import type {OverlayProps} from '../Overlay'
-import {useProvidedStateOrCreate, useMenuKeyboardNavigation, useMergedRefs} from '../hooks'
+import {useProvidedRefOrCreate, useProvidedStateOrCreate, useMenuKeyboardNavigation} from '../hooks'
 import {Divider} from '../ActionList/Divider'
 import {ActionListContainerContext} from '../ActionList/ActionListContainerContext'
 import type {ButtonProps} from '../Button'
@@ -115,9 +115,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
   )
   const menuButtonChildId = React.isValidElement(menuButtonChild) ? menuButtonChild.props.id : undefined
 
-  const anchorRef = useRef<HTMLElement>(null)
-  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
-
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const anchorId = useId(menuButtonChildId)
   let renderAnchor: AnchoredOverlayProps['renderAnchor'] = null
   // 🚨 Hack for good API!
@@ -137,7 +135,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
             anchorChildren,
             mergeAnchorHandlers({...anchorProps}, anchorChildren.props),
           )
-          return React.cloneElement(child, {children: triggerButton, ref: mergedRef})
+          return React.cloneElement(child, {children: triggerButton, ref: anchorRef})
         }
       }
       return null
@@ -156,7 +154,7 @@ const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
               mergeAnchorHandlers({...anchorProps}, tooltipTrigger.props),
             )
             const tooltip = React.cloneElement(anchorChildren, {children: tooltipTriggerEl})
-            return React.cloneElement(child, {children: tooltip, ref: mergedRef})
+            return React.cloneElement(child, {children: tooltip, ref: anchorRef})
           }
         }
       } else {
@@ -290,7 +288,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
   // we typecast anchorRef as required instead of optional
   // because we know that we're setting it in context in Menu
   const {
-    anchorRef: contextAnchorRef,
+    anchorRef,
     renderAnchor,
     anchorId,
     open,
@@ -299,9 +297,6 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
     isSubmenu = false,
   } = React.useContext(MenuContext) as MandateProps<MenuContextProps, 'anchorRef'>
 
-  const anchorRef = useRef<HTMLElement>(null)
-  const mergedAnchorRef = useMergedRefs(anchorRef, contextAnchorRef)
-
   const containerRef = React.useRef<HTMLDivElement>(null)
   const isNarrow = useResponsiveValue({narrow: true}, false)
 
@@ -345,7 +340,7 @@ const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
 
   return (
     <AnchoredOverlay
-      anchorRef={mergedAnchorRef}
+      anchorRef={anchorRef}
       renderAnchor={renderAnchor}
       anchorId={anchorId}
       open={open}
diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
index e71a731567d..31b14edd94e 100644
--- a/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
+++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.tsx
@@ -6,7 +6,7 @@ import type {FocusTrapHookSettings} from '../hooks/useFocusTrap'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useFocusZone} from '../hooks/useFocusZone'
-import {useAnchoredPosition, useMergedRefs, useRenderForcingRef} from '../hooks'
+import {useAnchoredPosition, useMergedRefs, useProvidedRefOrCreate, useRenderForcingRef} from '../hooks'
 import {useId} from '../hooks/useId'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
 import {type ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -28,7 +28,7 @@ interface AnchoredOverlayPropsWithAnchor {
   /**
    * An override to the internal ref that will be spread on to the renderAnchor
    */
-  anchorRef?: React.Ref<HTMLElement | null>
+  anchorRef?: React.RefObject<HTMLElement | null>
 
   /**
    * An override to the internal id that will be spread on to the renderAnchor
@@ -47,7 +47,7 @@ interface AnchoredOverlayPropsWithoutAnchor {
    * An override to the internal renderAnchor ref that will be used to position the overlay.
    * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
    */
-  anchorRef: React.Ref<HTMLElement | null>
+  anchorRef: React.RefObject<HTMLElement | null>
   /**
    * An override to the internal id that will be spread on to the renderAnchor
    */
@@ -173,12 +173,9 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
   closeButtonProps = defaultCloseButtonProps,
 }) => {
   const cssAnchorPositioning = useFeatureFlag('primer_react_css_anchor_positioning')
-  const anchorRef = useRef<HTMLElement>(null)
-  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
-
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
   const mergedOverlayRef = useMergedRefs(updateOverlayRef, overlayProps?.ref)
-
   const anchorId = useId(externalAnchorId)
 
   const onClickOutside = useCallback(() => onClose?.('click-outside'), [onClose])
@@ -261,7 +258,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
     <>
       {renderAnchor &&
         renderAnchor({
-          ref: mergedRef,
+          ref: anchorRef,
           id: anchorId,
           'aria-haspopup': 'true',
           'aria-expanded': open,
diff --git a/packages/react/src/SelectPanel/SelectPanel.tsx b/packages/react/src/SelectPanel/SelectPanel.tsx
index 061abb5c5d5..82cd0812d1b 100644
--- a/packages/react/src/SelectPanel/SelectPanel.tsx
+++ b/packages/react/src/SelectPanel/SelectPanel.tsx
@@ -12,7 +12,7 @@ import type {ItemProps, ItemInput} from './'
 import {SelectPanelMessage} from './SelectPanelMessage'
 
 import {Button, IconButton, LinkButton} from '../Button'
-import {useMergedRefs} from '../hooks'
+import {useProvidedRefOrCreate} from '../hooks'
 import type {FocusZoneHookSettings} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
@@ -513,9 +513,7 @@ function Panel({
     }
   }, [notice, open])
 
-  const anchorRef = useRef<HTMLElement>(null)
-  const mergedAnchorRef = useMergedRefs(anchorRef, externalAnchorRef)
-
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const onOpen: AnchoredOverlayProps['onOpen'] = useCallback(
     (gesture: Parameters<Exclude<AnchoredOverlayProps['onOpen'], undefined>>[0]) => onOpenChange(true, gesture),
     [onOpenChange],
@@ -862,7 +860,7 @@ function Panel({
     <>
       <AnchoredOverlay
         renderAnchor={renderMenuAnchor}
-        anchorRef={mergedAnchorRef}
+        anchorRef={anchorRef}
         align={align}
         open={open}
         onOpen={onOpen}
diff --git a/packages/react/src/deprecated/ActionMenu.tsx b/packages/react/src/deprecated/ActionMenu.tsx
index 43cf9371151..fa0cf1de949 100644
--- a/packages/react/src/deprecated/ActionMenu.tsx
+++ b/packages/react/src/deprecated/ActionMenu.tsx
@@ -6,11 +6,11 @@ import {Divider} from './ActionList/Divider'
 import type {ButtonProps} from '../Button'
 import {Button} from '../Button'
 import type React from 'react'
-import {useCallback, useMemo, useRef, type JSX} from 'react'
+import {useCallback, useMemo, type JSX} from 'react'
 import {AnchoredOverlay} from '../AnchoredOverlay'
 import {useProvidedStateOrCreate} from '../hooks/useProvidedStateOrCreate'
 import type {OverlayProps} from '../Overlay'
-import {useMergedRefs} from '../hooks'
+import {useProvidedRefOrCreate} from '../hooks'
 import type {AnchoredOverlayWrapperAnchorProps} from '../AnchoredOverlay/AnchoredOverlay'
 
 interface ActionMenuBaseProps extends Partial<Omit<GroupedListProps, keyof ListPropsBase>>, ListPropsBase {
@@ -60,8 +60,7 @@ const ActionMenuBase = ({
   ...listProps
 }: ActionMenuProps): JSX.Element => {
   const [combinedOpenState, setCombinedOpenState] = useProvidedStateOrCreate(open, setOpen, false)
-  const anchorRef = useRef<HTMLElement>(null)
-  const mergedRef = useMergedRefs(anchorRef, externalAnchorRef)
+  const anchorRef = useProvidedRefOrCreate(externalAnchorRef)
   const onOpen = useCallback(() => setCombinedOpenState(true), [setCombinedOpenState])
   const onClose = useCallback(() => setCombinedOpenState(false), [setCombinedOpenState])
 
@@ -97,7 +96,7 @@ const ActionMenuBase = ({
   return (
     <AnchoredOverlay
       renderAnchor={renderMenuAnchor}
-      anchorRef={mergedRef}
+      anchorRef={anchorRef}
       open={combinedOpenState}
       onOpen={onOpen}
       onClose={onClose}
diff --git a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
index 05d0e3c98f7..3e61548d52b 100644
--- a/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
+++ b/packages/react/src/experimental/SelectPanel2/SelectPanel.tsx
@@ -1,4 +1,4 @@
-import React, {useEffect, useRef, useState, type MutableRefObject} from 'react'
+import React, {useEffect, useState, type MutableRefObject} from 'react'
 import {SearchIcon, XCircleFillIcon, XIcon, FilterRemoveIcon, AlertIcon, ArrowLeftIcon} from '@primer/octicons-react'
 
 import type {ButtonProps, TextInputProps, ActionListProps, LinkProps, CheckboxProps} from '../../index'
@@ -15,7 +15,7 @@ import {
 import Octicon from '../../Octicon'
 import {ActionListContainerContext} from '../../ActionList/ActionListContainerContext'
 import {useSlots} from '../../hooks/useSlots'
-import {useId, useAnchoredPosition, useMergedRefs} from '../../hooks'
+import {useProvidedRefOrCreate, useId, useAnchoredPosition} from '../../hooks'
 import type {OverlayProps} from '../../Overlay/Overlay'
 import {BaseOverlay, heightMap} from '../../Overlay/Overlay'
 import {InputLabel} from '../../internal/components/InputLabel'
@@ -118,9 +118,7 @@ const Panel: React.FC<SelectPanelProps> = ({
   // with additional props for accessibility
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let Anchor: React.ReactElement<any> | undefined
-
-  const anchorRef = useRef<HTMLButtonElement>(null)
-  const mergedRef = useMergedRefs(providedAnchorRef, anchorRef)
+  const anchorRef = useProvidedRefOrCreate(providedAnchorRef)
 
   const onAnchorClick = () => {
     if (!internalOpen) setInternalOpen(true)
@@ -131,7 +129,8 @@ const Panel: React.FC<SelectPanelProps> = ({
     if (React.isValidElement(child) && (child.type === SelectPanelButton || isSlot(child, SelectPanelButton))) {
       // eslint-disable-next-line react-hooks/immutability
       Anchor = React.cloneElement(child, {
-        ref: mergedRef,
+        // @ts-ignore TODO
+        ref: anchorRef,
         onClick: child.props.onClick || onAnchorClick,
         'aria-haspopup': true,
         'aria-expanded': internalOpen,
diff --git a/packages/react/src/hooks/useAnchoredPosition.ts b/packages/react/src/hooks/useAnchoredPosition.ts
index b86e6f5ebdb..32777aad1d7 100644
--- a/packages/react/src/hooks/useAnchoredPosition.ts
+++ b/packages/react/src/hooks/useAnchoredPosition.ts
@@ -1,9 +1,9 @@
 import React from 'react'
 import {getAnchoredPosition} from '@primer/behaviors'
 import type {AnchorPosition, PositionSettings} from '@primer/behaviors'
+import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 import {useResizeObserver} from './useResizeObserver'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
-import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
 
 export interface AnchoredPositionHookSettings extends Partial<PositionSettings> {
   floatingElementRef?: React.RefObject<Element | null>
diff --git a/packages/react/src/hooks/useFocusTrap.ts b/packages/react/src/hooks/useFocusTrap.ts
index ed09cb36f8b..70b80072d51 100644
--- a/packages/react/src/hooks/useFocusTrap.ts
+++ b/packages/react/src/hooks/useFocusTrap.ts
@@ -1,7 +1,7 @@
 import React from 'react'
 import {focusTrap} from '@primer/behaviors'
-import {useOnOutsideClick} from './useOnOutsideClick'
 import {useProvidedRefOrCreate} from './useProvidedRefOrCreate'
+import {useOnOutsideClick} from './useOnOutsideClick'
 
 export interface FocusTrapHookSettings {
   /**
@@ -53,10 +53,8 @@ export function useFocusTrap(
   dependencies: React.DependencyList = [],
 ): {containerRef: React.RefObject<HTMLElement | null>; initialFocusRef: React.RefObject<HTMLElement | null>} {
   const [outsideClicked, setOutsideClicked] = React.useState(false)
-
   const containerRef = useProvidedRefOrCreate(settings?.containerRef)
   const initialFocusRef = useProvidedRefOrCreate(settings?.initialFocusRef)
-
   const disabled = settings?.disabled
   const abortController = React.useRef<AbortController>()
   const previousFocusedElement = React.useRef<Element | null>(null)

From dda43826c604d076269292b3e5886153d65f7c11 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 19:30:28 +0000
Subject: [PATCH 16/18] Update `useProvidedRefOrCreate` to remove deprecation
 comment

---
 .../react/src/hooks/useProvidedRefOrCreate.ts | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/packages/react/src/hooks/useProvidedRefOrCreate.ts b/packages/react/src/hooks/useProvidedRefOrCreate.ts
index bec68d8dabd..99f99e8d64f 100644
--- a/packages/react/src/hooks/useProvidedRefOrCreate.ts
+++ b/packages/react/src/hooks/useProvidedRefOrCreate.ts
@@ -1,5 +1,9 @@
 import React from 'react'
 
+// used in doc comment
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import type {useMergedRefs} from './useMergedRefs'
+
 /**
  * There are some situations where we only want to create a new ref if one is not provided to a component
  * or hook as a prop. However, due to the `rules-of-hooks`, we cannot conditionally make a call to `React.useRef`
@@ -8,17 +12,14 @@ import React from 'react'
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
  * @type TRef The type of the RefObject which should be created.
  *
- * @deprecated This hook is incompatible with forwarded callback refs. Prefer `useMergedRefs` with an internally
- * created ref instead.
- *
- * ```diff
- * - const ref = useProvidedRefOrCreate(forwardedRef as RefObject<...>)
- * + const ref = useRef(null)
- * + const mergedRef = useMergedRefs(forwardedRef, ref)
+ * @note This hook is overly restrictive in that it forces the provided ref to be a ref object rather than a callback.
+ * In particular, it should **not** be used to merge internal refs with forwarded refs. For this, use
+ * {@linkcode useMergedRefs} instead.
  *
- * - return <div ref={ref} />
- * + return <div ref={mergedRef} />
- * ```
+ * The primary valid use case for this hook is for when the consumer is using the provided ref to point to an external
+ * element, like an externally rendered anchor. This is 'backwards' from forwarded refs with respect to data flow; the
+ * consumer is passing a reference to an external element, rather than passing a handle to obtain a reference to an
+ * internal element.
  */
 export function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef | null>): React.RefObject<TRef | null> {
   const createdRef = React.useRef<TRef>(null)

From f86b058c5da2cab105c54d97a83308a1c44e152d Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 19:41:23 +0000
Subject: [PATCH 17/18] Don't return a callback ref in React 18-

---
 packages/react/src/hooks/useMergedRefs.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/hooks/useMergedRefs.ts b/packages/react/src/hooks/useMergedRefs.ts
index a80b63f8e72..bfc16917965 100644
--- a/packages/react/src/hooks/useMergedRefs.ts
+++ b/packages/react/src/hooks/useMergedRefs.ts
@@ -1,5 +1,7 @@
 import type {ForwardedRef, Ref as StandardRef, MutableRefObject} from 'react'
-import {useCallback} from 'react'
+import {useCallback, version} from 'react'
+
+const majorReactVersion = parseInt(version.split('.')[0] ?? '18', 10)
 
 /**
  * Combine two refs of matching type (typically an external or forwarded ref and an internal `useRef` object or
@@ -37,8 +39,10 @@ export function useMergedRefs<T>(refA: Ref<T | null>, refB: Ref<T | null>) {
       const cleanupA = setRef(refA, value)
       const cleanupB = setRef(refB, value)
 
-      // Only works in React 19. In React 18, the cleanup function will be ignored and the ref will get called with
+      // Callback refs only work in React 19+. In React 18, the ref will get called with
       // `null` which will be passed to each ref as expected.
+      if (majorReactVersion <= 18) return
+
       return () => {
         // For object refs and callback refs that don't return cleanups, we still need to pass `null` on cleanup
         if (cleanupA) cleanupA()

From c0612a7a2fdb34ec4fbb3fd3dfd86d18696bfc64 Mon Sep 17 00:00:00 2001
From: Ian Sanders <iansan5653@github.com>
Date: Tue, 24 Mar 2026 19:48:30 +0000
Subject: [PATCH 18/18] Update tests

---
 packages/react/src/hooks/__tests__/useMergedRefs.test.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
index 43ef7f8d706..87fec1f36ce 100644
--- a/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
+++ b/packages/react/src/hooks/__tests__/useMergedRefs.test.tsx
@@ -1,5 +1,5 @@
 import {render, renderHook} from '@testing-library/react'
-import React, {forwardRef, type RefObject} from 'react'
+import React, {forwardRef, type RefObject, version} from 'react'
 import {describe, expect, it, vi} from 'vitest'
 import {useMergedRefs} from '../useMergedRefs'
 
@@ -114,7 +114,7 @@ describe('useMergedRefs', () => {
       expect(refB).toHaveBeenCalledExactlyOnceWith('test')
     })
 
-    it('handles React 18 null values correctly', () => {
+    it.runIf(version.startsWith('18'))('handles React 18 null values correctly', () => {
       const refA = vi.fn()
       const refB = vi.fn()
 
@@ -131,7 +131,7 @@ describe('useMergedRefs', () => {
       expect(refB).toHaveBeenCalledWith(null)
     })
 
-    it('handles React 19 cleanup functions correctly and independently', () => {
+    it.skipIf(version.startsWith('18'))('handles React 19 cleanup functions correctly and independently', () => {
       const refA = vi.fn()
       const cleanupRefB = vi.fn()
       const refB = vi.fn().mockReturnValue(cleanupRefB)
@@ -143,7 +143,7 @@ describe('useMergedRefs', () => {
       expect(refB).toHaveBeenCalledWith('test')
 
       // React 19 will call cleanup function and not pass null
-      cleanup()
+      cleanup!()
 
       expect(refA).toHaveBeenCalledWith(null)
       expect(refB).not.toHaveBeenCalledWith(null)