Update useCombinedRefs to useMergedRefs

iansan5653 · web-flow · commit 006cc27654a9 · 2026-03-17T17:00:55.000Z
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>) {
