useRefObjectAsForwardedRef had a bug where useImperativeHandle would re-call on every render, risking infinite loops when combined with state-setting callback refs. This PR replaces it with a useCombinedRefs hook that uses a callback ref as its trigger, so refs are only updated when the target actually changes.

Key improvements over useRefObjectAsForwardedRef

• No infinite loop risk: callback-ref-based trigger avoids re-firing on every render
• React 19 compatible: handles cleanup functions returned by callback refs; remains React 18 compatible
• Accepts undefined: works ergonomically with optional React 19 ref props
• Order-agnostic: no silent failure if argument order is swapped
• Supports two callback refs: internal callback refs can coexist with external refs
• Better types: reduces need for casting

Usage

// React 18
const Example = forwardRef<HTMLButtonElement>((props, forwardedRef) => {
  const ref = useRef<HTMLButtonElement>(null)
  const combinedRef = useCombinedRefs(forwardedRef, ref)
  return <button ref={combinedRef} />
})

// React 19
const Example = ({ref: externalRef}: {ref?: Ref<HTMLButtonElement>}) => {
  const ref = useRef<HTMLButtonElement>(null)
  const combinedRef = useCombinedRefs(externalRef, ref)
  return <button ref={combinedRef} />
}

For more than two refs: useCombinedRefs(refA, useCombinedRefs(refB, refC))

Migration from useRefObjectAsForwardedRef

  const ref = useRef(null)

- useRefObjectAsForwardedRef(forwardedRef, ref)
+ const combinedRef = useCombinedRefs(forwardedRef, ref)

- return <div ref={ref} />
+ return <div ref={combinedRef} />

useRefObjectAsForwardedRef is deprecated (not removed) to allow a gradual migration; it will be deleted in the next major release.

Changelog

New

• useCombinedRefs hook

Changed

• useRefObjectAsForwardedRef deprecated with inline migration instructions
• Migrated ButtonBase, Dialog, Heading, Link, Overlay, PageLayout, AutocompleteInput, AutocompleteOverlay, TextInputWithTokens, and deprecated/Dialog to useCombinedRefs

Removed

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Unit tests cover: forwarding to object refs, callback refs, React 19 cleanup callbacks, null/undefined handling, and combined callback+object ref scenarios.

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.