primer · iansan5653 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026 · Mar 17, 2026
@@ -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 {useMergedRefs} from '../hooks'
 import {FocusKeys, useFocusZone} from '../hooks/useFocusZone'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
@@ -43,7 +43,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 mergedRef = useMergedRefs(forwardedRef, listRef)
   const itemGapEnabled = useFeatureFlag('primer_react_action_list_item_gap') && container === 'NavList'
 
   let enableFocusZone = false
@@ -100,12 +101,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={mergedRef}
         data-component="ActionList"
         data-dividers={showDividers}
         data-variant={variant}

@@ -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, useProvidedRefOrCreate, 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'
@@ -207,6 +207,7 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
     setAnchorElement(anchorRef.current)
   }
   const [overlayRef, updateOverlayRef] = useRenderForcingRef<HTMLDivElement>()
+  const mergedOverlayRef = useMergedRefs(updateOverlayRef, overlayProps?.ref)
   const [overlayElement, setOverlayElement] = useState<HTMLDivElement | null>(null)
   const anchorId = useId(externalAnchorId)
 
@@ -436,12 +437,10 @@ export const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayPr
           {...(shouldRenderAsPopover ? {popover: 'manual'} : {})}
           {...restOverlayProps}
           {...(shouldRenderAsPopover ? {id: popoverId} : {})}
+          {...(cssAnchorPositioning ? {id: popoverId} : {})}
           ref={node => {
-            if (overlayProps?.ref) {
-              assignRef(overlayProps.ref, node)
-            }
-            updateOverlayRef(node)
             setOverlayElement(node)
+            assignRef(mergedOverlayRef, node)
           }}
           data-anchor-position={cssAnchorPositioning}
           data-side={cssAnchorPositioning ? side : position?.anchorSide}

@@ -56,13 +56,19 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputBlur: FocusEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onBlur && onBlur(event)
+        onBlur?.(event)
 
-        // HACK: wait a tick and check the focused element before hiding the autocomplete menu
-        // this prevents the menu from hiding when the user is clicking an option in the Autoselect.Menu,
-        // but still hides the menu when the user blurs the input by tabbing out or clicking somewhere else on the page
+        // HACK: wait a tick before hiding the menu so click interactions can complete.
+        // Use the blur event's relatedTarget to determine whether focus is moving into the
+        // autocomplete menu; if not, hide the menu when focus leaves the input.
         safeSetTimeout(() => {
-          if (document.activeElement !== inputRef.current) {
+          const nextFocusedElement = event.relatedTarget as Node | null
+          const menuElement = document.getElementById(`${id}-listbox`)
+
+          if (
+            !nextFocusedElement ||
+            (nextFocusedElement !== menuElement && !menuElement?.contains(nextFocusedElement))
+          ) {
             setShowMenu(false)
 
             // Reset the input's value to the text the user actually typed rather than leaving the
@@ -75,11 +81,11 @@ const AutocompleteInput = React.forwardRef(
           }
         }, 0)
       },
-      [onBlur, setShowMenu, inputRef, safeSetTimeout, autocompleteSuggestion, inputValue],
+      [onBlur, setShowMenu, inputRef, safeSetTimeout, autocompleteSuggestion, inputValue, id],
     )
 
     const handleInputChange: ChangeEventHandler<HTMLInputElement> = event => {
-      onChange && onChange(event)
+      onChange?.(event)
       setInputValue(event.currentTarget.value)
       if (!showMenu) {
         setShowMenu(true)
@@ -88,7 +94,7 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputKeyDown: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyDown && onKeyDown(event)
+        onKeyDown?.(event)
 
         if (event.key === 'Backspace') {
           setHighlightRemainingText(false)
@@ -107,7 +113,7 @@ const AutocompleteInput = React.forwardRef(
 
     const handleInputKeyUp: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyUp && onKeyUp(event)
+        onKeyUp?.(event)
 
         if (event.key === 'Backspace') {
           setHighlightRemainingText(true)
@@ -118,12 +124,11 @@ const AutocompleteInput = React.forwardRef(
 
     const onInputKeyPress: KeyboardEventHandler<HTMLInputElement> = useCallback(
       event => {
-        onKeyPress && onKeyPress(event)
+        onKeyPress?.(event)
         if (showMenu && event.key === 'Enter' && activeDescendantRef.current) {
           event.preventDefault()
           event.nativeEvent.stopImmediatePropagation()
 
-          // Forward Enter key press to active descendant so that item gets activated
           const activeDescendantEvent = new KeyboardEvent(event.type, event.nativeEvent)
           activeDescendantRef.current.dispatchEvent(activeDescendantEvent)
         }
@@ -136,17 +141,10 @@ const AutocompleteInput = React.forwardRef(
         return
       }
 
-      // resets input value to being empty after a selection has been made
       if (!autocompleteSuggestion) {
         inputRef.current.value = inputValue
       }
 
-      // TODO: fix bug where this function prevents `onChange` from being triggered if the highlighted item text
-      //       is the same as what I'm typing
-      //       e.g.: typing 'tw' highlights 'two', but when I 'two', the text input change does not get triggered
-      // Only apply the inline autocomplete suggestion while the input is focused. Without this guard,
-      // the suggestion can be re-applied to the DOM after the input is blurred, which would restore
-      // the full suggestion the user was editing away from. See https://github.com/primer/react/issues/4275
       const isInputFocused = document.activeElement === inputRef.current
 
       if (
@@ -163,7 +161,6 @@ const AutocompleteInput = React.forwardRef(
         }
       }
 
-      // calling this useEffect when `highlightRemainingText` changes breaks backspace functionality
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [autocompleteSuggestion, inputValue, inputRef, isMenuDirectlyActivated])
 

@@ -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 {useMergedRefs} from '../hooks'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 
 export type ButtonGroupProps = PropsWithChildren<{
@@ -16,12 +16,13 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
   {as: BaseComponent = 'div', children, className, role, ...rest},
   forwardRef,
 ) {
+  const buttonRef = useRef<HTMLDivElement>(null)
+  const mergedRef = useMergedRefs(buttonRef, forwardRef)
   const buttons = React.Children.map(children, (child, index) => (
     <div key={index} className={classes.Item}>
       {child}
     </div>
   ))
-  const buttonRef = useProvidedRefOrCreate(forwardRef as React.RefObject<HTMLDivElement | null>)
 
   useFocusZone({
     containerRef: buttonRef,
@@ -32,8 +33,7 @@ const ButtonGroup = React.forwardRef(function ButtonGroup(
 
   return (
     <BaseComponent
-      //@ts-expect-error it needs a non nullable ref
-      ref={buttonRef}
+      ref={mergedRef}
       className={clsx(className, classes.ButtonGroup)}
       role={role}
       {...rest}

@@ -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 {useMergedRefs} 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'
@@ -58,7 +65,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 mergedRef = useMergedRefs(checkboxRef, ref)
     const checkboxGroupContext = useContext(CheckboxGroupContext)
     const handleOnChange: ChangeEventHandler<HTMLInputElement> = e => {
       checkboxGroupContext.onChange && checkboxGroupContext.onChange(e)
@@ -72,7 +80,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     const inputProps = {
       type: 'checkbox',
       disabled,
-      ref: checkboxRef,
+      ref: mergedRef,
       checked: indeterminate ? false : checked,
       defaultChecked,
       required,
@@ -103,7 +111,6 @@ const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
       }
     })
     return (
-      // @ts-expect-error inputProp needs a non nullable ref
       <input
         {...inputProps}
         data-component={dataComponent ?? 'Checkbox'}

@@ -1,7 +1,7 @@
 import React, {useCallback, useEffect, useRef, useState, type CSSProperties, type SyntheticEvent} from 'react'
 import type {ButtonProps} from '../Button'
 import {Button, IconButton} from '../Button'
-import {useMergedRefs, useOnEscapePress, useProvidedRefOrCreate} from '../hooks'
+import {useMergedRefs, useOnEscapePress} from '../hooks'
 import {useFocusTrap} from '../hooks/useFocusTrap'
 import {XIcon} from '@primer/octicons-react'
 import {useFocusZone} from '../hooks/useFocusZone'
@@ -484,7 +484,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 mergedRef = useMergedRefs(autoFocusRef, buttons.find(button => button.autoFocus)?.ref)
   let autoFocusCount = 0
   const [hasRendered, setHasRendered] = useState(0)
   useEffect(() => {
@@ -508,8 +509,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++, mergedRef) : null}
           >
             {content}
           </Button>

@@ -8,7 +8,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'
@@ -21,6 +20,7 @@ import {isValidElementType} from 'react-is'
 import {useAnnouncements} from './useAnnouncements'
 import {clsx} from 'clsx'
 import {useVirtualizer} from '@tanstack/react-virtual'
+import {useMergedRefs} from '../hooks'
 import {FilteredActionListInput} from './FilteredActionListInput'
 
 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 = useMergedRefs(scrollContainerRef, providedScrollContainerRef)
+
+  const inputRef = useRef<HTMLInputElement>(null)
+  const combinedInputRef = useMergedRefs(inputRef, providedInputRef)
 
   const usingRovingTabindex = _PrivateFocusManagement === 'roving-tabindex'
   const [listContainerElement, setListContainerElement] = useState<HTMLUListElement | null>(null)
@@ -559,7 +560,7 @@ export function FilteredActionList({
       data-component="FilteredActionList"
     >
       <FilteredActionListInput
-        inputRef={inputRef}
+        inputRef={combinedInputRef}
         value={filterValue}
         onInputChange={onInputChange}
         onInputKeyPress={onInputKeyPress}
@@ -591,8 +592,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>

@@ -5,7 +5,7 @@ import type {TextInputProps} from '../TextInput'
 import classes from './FilteredActionList.module.css'
 
 export interface FilteredActionListInputProps extends Partial<Omit<TextInputProps, 'onChange' | 'onKeyDown'>> {
-  inputRef: React.RefObject<HTMLInputElement | null>
+  inputRef: React.Ref<HTMLInputElement | null>
   onInputChange?: (e: React.ChangeEvent<HTMLInputElement>) => void
   onInputKeyPress?: React.KeyboardEventHandler<HTMLInputElement>
   onInputKeyDown?: React.KeyboardEventHandler<HTMLInputElement>

@@ -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 {useMergedRefs} 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 mergedRef = useMergedRefs(rootRef, forwardedRef)
 
     const isInteractive = (element: HTMLElement) => {
       return (
@@ -105,7 +106,7 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
 
     return (
       <BaseComponent
-        ref={rootRef}
+        ref={mergedRef}
         className={clsx(classes.PageHeader, className)}
         data-component="PageHeader"
         data-has-border={hasBorder ? 'true' : undefined}
@@ -220,12 +221,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)}