Replace deprecated ref helper usage (#7834)

joshblack · Copilot · Copilot · web-flow · commit d3c8fe2b5891 · 2026-05-14T16:24:12.000Z
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
diff --git a/packages/react/src/ActionBar/ActionBar.tsx b/packages/react/src/ActionBar/ActionBar.tsx
@@ -9,7 +9,7 @@ import {ActionMenu} from '../ActionMenu'
 import {useFocusZone, FocusKeys} from '../hooks/useFocusZone'
 import styles from './ActionBar.module.css'
 import {clsx} from 'clsx'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import {createDescendantRegistry} from '../utils/descendant-registry'
 
 type ChildProps =
@@ -348,7 +348,7 @@ function useActionBarItem(ref: React.RefObject<HTMLElement | null>, registryProp
 export const ActionBarIconButton = forwardRef(
   ({disabled, onClick, ...props}: ActionBarIconButtonProps, forwardedRef) => {
     const ref = useRef<HTMLButtonElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, ref)
+    const mergedRef = useMergedRefs(forwardedRef, ref)
 
     const {size} = React.useContext(ActionBarContext)
 
@@ -379,7 +379,7 @@ export const ActionBarIconButton = forwardRef(
     return (
       <IconButton
         aria-disabled={disabled}
-        ref={ref}
+        ref={mergedRef}
         size={size}
         onClick={clickHandler}
         {...props}
diff --git a/packages/react/src/ActionList/Heading.tsx b/packages/react/src/ActionList/Heading.tsx
@@ -1,5 +1,5 @@
 import React, {forwardRef} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {default as HeadingComponent} from '../Heading'
 import {ListContext} from './shared'
@@ -21,7 +21,7 @@ export type ActionListHeadingProps = {
 
 export const Heading = forwardRef(({as, size, children, visuallyHidden = false, className, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
   const {headingId: headingId, variant: listVariant} = React.useContext(ListContext)
   const {container} = React.useContext(ActionListContainerContext)
@@ -37,7 +37,7 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
       <HeadingComponent
         as={as}
         variant={size}
-        ref={innerRef}
+        ref={mergedRef}
         // use custom id if it is provided. Otherwise, use the id from the context
         id={props.id ?? headingId}
         className={clsx(className, classes.ActionListHeader)}
diff --git a/packages/react/src/Autocomplete/Autocomplete.test.tsx b/packages/react/src/Autocomplete/Autocomplete.test.tsx
@@ -155,9 +155,11 @@ describe('Autocomplete', () => {
 
       expect(inputNode.getAttribute('aria-expanded')).toBe('true')
 
-      await userEvent.tab()
+      // `userEvent.tab()` is unreliable in browser-mode Vitest for this case; blur is deterministic.
+      // eslint-disable-next-line github/no-blur
+      fireEvent.blur(inputNode)
 
-      expect(inputNode.getAttribute('aria-expanded')).not.toBe('true')
+      await waitFor(() => expect(inputNode.getAttribute('aria-expanded')).not.toBe('true'))
     })
 
     it('sets the input value to the suggested item text and highlights the untyped part of the word', async () => {
diff --git a/packages/react/src/Autocomplete/AutocompleteInput.tsx b/packages/react/src/Autocomplete/AutocompleteInput.tsx
@@ -3,7 +3,7 @@ import React, {useCallback, useContext, useEffect, useState} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import {AutocompleteContext, AutocompleteInputContext} from './AutocompleteContext'
 import TextInput from '../TextInput'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import type {ComponentProps} from '../utils/types'
 import useSafeTimeout from '../hooks/useSafeTimeout'
 
@@ -43,7 +43,7 @@ const AutocompleteInput = React.forwardRef(
     }
     const {activeDescendantRef, id, inputRef, setInputValue, setShowMenu, showMenu} = autocompleteContext
     const {autocompleteSuggestion = '', inputValue = '', isMenuDirectlyActivated} = inputContext
-    useRefObjectAsForwardedRef(forwardedRef, inputRef)
+    const mergedRef = useMergedRefs(forwardedRef, inputRef)
     const [highlightRemainingText, setHighlightRemainingText] = useState<boolean>(true)
     const {safeSetTimeout} = useSafeTimeout()
 
@@ -160,7 +160,7 @@ const AutocompleteInput = React.forwardRef(
         onKeyDown={handleInputKeyDown}
         onKeyPress={onInputKeyPress}
         onKeyUp={handleInputKeyUp}
-        ref={inputRef}
+        ref={mergedRef}
         aria-controls={`${id}-listbox`}
         aria-autocomplete="both"
         role="combobox"
diff --git a/packages/react/src/Autocomplete/AutocompleteOverlay.tsx b/packages/react/src/Autocomplete/AutocompleteOverlay.tsx
@@ -5,7 +5,7 @@ import type {OverlayProps} from '../Overlay'
 import Overlay from '../Overlay'
 import type {ComponentProps} from '../utils/types'
 import {AutocompleteContext} from './AutocompleteContext'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import VisuallyHidden from '../_VisuallyHidden'
 
 import classes from './AutocompleteOverlay.module.css'
@@ -57,7 +57,7 @@ function AutocompleteOverlay({
     [showMenu, selectedItemLength],
   )
 
-  useRefObjectAsForwardedRef(scrollContainerRef, floatingElementRef)
+  const mergedScrollContainerRef = useMergedRefs(scrollContainerRef, floatingElementRef)
 
   const closeOptionList = useCallback(() => {
     setShowMenu(false)
@@ -73,7 +73,7 @@ function AutocompleteOverlay({
       preventFocusOnOpen={true}
       onClickOutside={closeOptionList}
       onEscape={closeOptionList}
-      ref={floatingElementRef as React.RefObject<HTMLDivElement>}
+      ref={mergedScrollContainerRef}
       top={position?.top}
       left={position?.left}
       className={clsx(classes.Overlay, className)}
diff --git a/packages/react/src/Button/ButtonBase.tsx b/packages/react/src/Button/ButtonBase.tsx
@@ -1,7 +1,7 @@
 import React, {forwardRef, type JSX} from 'react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import type {ButtonProps} from './types'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {VisuallyHidden} from '../VisuallyHidden'
 import Spinner from '../Spinner'
 import CounterLabel from '../CounterLabel'
@@ -51,7 +51,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
   } = props
 
   const innerRef = React.useRef<HTMLButtonElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
   const uuid = useId(id)
   const loadingAnnouncementID = `${uuid}-loading-announcement`
@@ -89,7 +89,7 @@ const ButtonBase = forwardRef(({children, as: Component = 'button', ...props}, f
         data-component="Button"
         {...rest}
         // @ts-ignore temporary disable as we migrate to css modules, until we remove PolymorphicForwardRefComponent
-        ref={innerRef}
+        ref={mergedRef}
         className={clsx(classes.ButtonBase, className)}
         data-block={block ? 'block' : null}
         data-inactive={inactive ? true : undefined}
diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx
@@ -1,13 +1,12 @@
 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 {useMergedRefs, useOnEscapePress, useProvidedRefOrCreate} from '../hooks'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {FocusKeys} from '@primer/behaviors'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import {useId} from '../hooks/useId'
 import {ScrollableRegion} from '../ScrollableRegion'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
@@ -302,7 +301,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
   })
 
   const dialogRef = useRef<HTMLDivElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, dialogRef)
+  const mergedDialogRef = useMergedRefs(forwardedRef, dialogRef)
   const backdropRef = useRef<HTMLDivElement>(null)
 
   useFocusTrap({
@@ -393,7 +392,7 @@ const _Dialog = React.forwardRef<HTMLDivElement, React.PropsWithChildren<DialogP
           }}
         >
           <div
-            ref={dialogRef}
+            ref={mergedDialogRef}
             role={role}
             aria-labelledby={dialogLabelId}
             aria-describedby={dialogDescriptionId}
diff --git a/packages/react/src/Heading/Heading.tsx b/packages/react/src/Heading/Heading.tsx
@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {forwardRef, useEffect} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import type {ComponentProps} from '../utils/types'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Heading.module.css'
@@ -14,7 +14,7 @@ type StyledHeadingProps = {
 
 const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}, forwardedRef) => {
   const innerRef = React.useRef<HTMLHeadingElement>(null)
-  useRefObjectAsForwardedRef(forwardedRef, innerRef)
+  const mergedRef = useMergedRefs(forwardedRef, innerRef)
 
   if (__DEV__) {
     /**
@@ -38,7 +38,7 @@ const Heading = forwardRef(({as: Component = 'h2', className, variant, ...props}
       data-variant={variant}
       data-component="Heading"
       {...props}
-      ref={innerRef}
+      ref={mergedRef}
     />
   )
 }) as PolymorphicForwardRefComponent<HeadingLevels, StyledHeadingProps>
diff --git a/packages/react/src/Link/Link.tsx b/packages/react/src/Link/Link.tsx
@@ -1,6 +1,6 @@
 import {clsx} from 'clsx'
 import React, {useEffect, type ForwardedRef, type ElementRef} from 'react'
-import {useRefObjectAsForwardedRef} from '../hooks'
+import {useMergedRefs} from '../hooks'
 import classes from './Link.module.css'
 import type {ComponentProps} from '../utils/types'
 import {type PolymorphicProps, fixedForwardRef} from '../utils/modern-polymorphic'
@@ -20,7 +20,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
 ) => {
   const {as: Component = 'a', className, inline, muted, hoverColor, ...restProps} = props
   const innerRef = React.useRef<ElementRef<As>>(null)
-  useRefObjectAsForwardedRef(ref, innerRef)
+  const mergedRef = useMergedRefs(ref, innerRef)
 
   if (__DEV__) {
     /**
@@ -55,7 +55,7 @@ export const UnwrappedLink = <As extends React.ElementType = 'a'>(
       data-hover-color={hoverColor}
       {...restProps}
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      ref={innerRef as any}
+      ref={mergedRef as any}
     />
   )
 }
diff --git a/packages/react/src/Overlay/Overlay.tsx b/packages/react/src/Overlay/Overlay.tsx
@@ -3,9 +3,8 @@ import React, {useEffect, useRef} from 'react'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 import type {AriaRole, Merge} from '../utils/types'
 import type {TouchOrMouseEvent} from '../hooks'
-import {useOverlay} from '../hooks'
+import {useMergedRefs, useOverlay} from '../hooks'
 import Portal from '../Portal'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import type {AnchorSide} from '@primer/behaviors'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import classes from './Overlay.module.css'
@@ -192,7 +191,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ): ReactElement<any> => {
     const overlayRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, overlayRef)
+    const mergedOverlayRef = useMergedRefs(forwardedRef, overlayRef)
     const slideAnimationDistance = 8 // var(--base-size-8), hardcoded to do some math
     const slideAnimationEasing = 'cubic-bezier(0.33, 1, 0.68, 1)'
     const cssAnchorPositioning = useFeatureFlag('primer_react_css_anchor_positioning')
@@ -237,7 +236,7 @@ const Overlay = React.forwardRef<HTMLDivElement, internalOverlayProps>(
         role={role}
         width={width}
         data-reflow-container={!preventOverflow ? true : undefined}
-        ref={overlayRef}
+        ref={mergedOverlayRef}
         left={leftPosition}
         right={right}
         height={height}
diff --git a/packages/react/src/PageLayout/PageLayout.tsx b/packages/react/src/PageLayout/PageLayout.tsx
@@ -1,7 +1,7 @@
 import React, {memo, useRef} from 'react'
 import {clsx} from 'clsx'
+import {useMergedRefs} from '../hooks'
 import {useId} from '../hooks/useId'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import type {ResponsiveValue} from '../hooks/useResponsiveValue'
 import {isResponsiveValue} from '../hooks/useResponsiveValue'
 import {useSlots} from '../hooks/useSlots'
@@ -838,7 +838,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
         currentWidth: controlledWidth,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, paneRef)
+    const mergedPaneRef = useMergedRefs(forwardRef, paneRef)
 
     const hasOverflow = useOverflow(paneRef)
 
@@ -887,7 +887,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
           position={positionProp}
         />
         <div
-          ref={paneRef}
+          ref={mergedPaneRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           // Not needed when onResizeEnd is provided (localStorage isn't read).
@@ -1136,7 +1136,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
         constrainToViewport: true,
       })
 
-    useRefObjectAsForwardedRef(forwardRef, sidebarRef)
+    const mergedSidebarRef = useMergedRefs(forwardRef, sidebarRef)
 
     const hasOverflow = useOverflow(sidebarRef)
 
@@ -1192,7 +1192,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLay
           />
         )}
         <div
-          ref={sidebarRef}
+          ref={mergedSidebarRef}
           // Suppress hydration mismatch for --pane-width when localStorage
           // provides a width that differs from the server-rendered default.
           suppressHydrationWarning={resizable === true && !!widthStorageKey}
diff --git a/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx b/packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx
@@ -3,7 +3,7 @@ import {isFocusable} from '@primer/behaviors/utils'
 import type {FocusEventHandler, KeyboardEventHandler, MouseEventHandler, RefObject} from 'react'
 import React, {useRef, useState} from 'react'
 import {isValidElementType} from 'react-is'
-import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../hooks/useMergedRefs'
 import {useFocusZone} from '../hooks/useFocusZone'
 import {useId} from '../hooks/useId'
 import Text from '../Text'
@@ -106,9 +106,9 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
   const {onBlur, onFocus, onKeyDown, 'aria-describedby': ariaDescribedByProp, role, ...inputPropsRest} = rest
 
   const ref = useRef<HTMLInputElement>(null)
+  const mergedRef = useMergedRefs(forwardedRef, ref)
 
   const selectedValuesDescriptionId = useId()
-  useRefObjectAsForwardedRef(forwardedRef, ref)
   const [selectedTokenIndex, setSelectedTokenIndex] = useState<number | undefined>()
   const [tokensAreTruncated, setTokensAreTruncated] = useState<boolean>(Boolean(visibleTokenCount))
   const selectedTokenTexts = tokens
@@ -314,7 +314,7 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
       >
         <div className={styles.InputWrapper}>
           <UnstyledTextInput
-            ref={ref}
+            ref={mergedRef}
             disabled={disabled}
             onFocus={handleInputFocus}
             onBlur={handleInputBlur}
diff --git a/packages/react/src/deprecated/DialogV1/Dialog.tsx b/packages/react/src/deprecated/DialogV1/Dialog.tsx
@@ -2,7 +2,7 @@ import React, {forwardRef, useRef, type HTMLAttributes} from 'react'
 import {IconButton} from '../../Button'
 import useDialog from '../../hooks/useDialog'
 import type {ComponentProps} from '../../utils/types'
-import {useRefObjectAsForwardedRef} from '../../hooks/useRefObjectAsForwardedRef'
+import {useMergedRefs} from '../../hooks/useMergedRefs'
 import {XIcon} from '@primer/octicons-react'
 import {clsx} from 'clsx'
 import classes from './Dialog.module.css'
@@ -48,7 +48,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
   ) => {
     const overlayRef = useRef(null)
     const modalRef = useRef<HTMLDivElement>(null)
-    useRefObjectAsForwardedRef(forwardedRef, modalRef)
+    const mergedRef = useMergedRefs(forwardedRef, modalRef)
     const closeButtonRef = useRef(null)
 
     const onCloseClick = () => {
@@ -73,7 +73,7 @@ const Dialog = forwardRef<HTMLDivElement, InternalDialogProps>(
         <span className={classes.Overlay} ref={overlayRef} />
         <Component
           tabIndex={-1}
-          ref={modalRef}
+          ref={mergedRef}
           role="dialog"
           aria-modal="true"
           {...props}
