Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix: add stable merged refs (#5266)

nynexman4464fac29533c652
diff --git a/.changeset/stable-text-refs.md b/.changeset/stable-text-refs.md
new file mode 100644
index 0000000000..70f39ed7cf
--- /dev/null
+++ b/.changeset/stable-text-refs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Add useMergedRefs and keep Text and Heading refs stable across rerenders.
+
+@nynexman4464
diff --git a/packages/core/src/Heading/Heading.test.tsx b/packages/core/src/Heading/Heading.test.tsx
index 9c0fe00f0c..e1158fa6c1 100644
--- a/packages/core/src/Heading/Heading.test.tsx
+++ b/packages/core/src/Heading/Heading.test.tsx
@@ -6,7 +6,7 @@
*/
import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
import {Heading} from './Heading';
describe('Heading', () => {
@@ -16,6 +16,28 @@ describe('Heading', () => {
expect(screen.getByText('Page Title')).toBeInTheDocument();
});
+ it('keeps a forwarded ref attached across rerenders', () => {
+ const ref = vi.fn();
+ const {rerender} = render(
+ <Heading ref={ref} level={1}>
+ Before
+ </Heading>,
+ );
+
+ const element = screen.getByText('Before');
+ expect(ref).toHaveBeenLastCalledWith(element);
+ ref.mockClear();
+
+ rerender(
+ <Heading ref={ref} level={1}>
+ After
+ </Heading>,
+ );
+
+ expect(ref).not.toHaveBeenCalled();
+ expect(screen.getByText('After')).toBe(element);
+ });
+
it('renders h1 for level 1', () => {
render(<Heading level={1}>H1</Heading>);
const element = screen.getByText('H1');
diff --git a/packages/core/src/Heading/Heading.tsx b/packages/core/src/Heading/Heading.tsx
index b702a03eab..5d6858a4c6 100644
--- a/packages/core/src/Heading/Heading.tsx
+++ b/packages/core/src/Heading/Heading.tsx
@@ -43,7 +43,8 @@ import {
import {useTruncation} from '../Text/useTruncation';
import {resolveStyleColor} from '../Text/Text';
import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
@@ -242,13 +243,16 @@ export function Heading({
// Ref for the heading element (used as tooltip anchor)
const headingRef = useRef<HTMLHeadingElement>(null);
+ // Keep the merged ref stable across rerenders.
+ const mergedRef = useMergedRefs(ref, truncation.ref, headingRef);
+
// Build inline style for -webkit-line-clamp (dynamic value)
const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;
return (
<>
<Component
- ref={mergeRefs(ref, truncation.ref, headingRef)}
+ ref={mergedRef}
{...mergeProps(
themeProps('heading', {level, color, ...(type && {type})}),
stylex.props(
diff --git a/packages/core/src/Text/Text.test.tsx b/packages/core/src/Text/Text.test.tsx
index 043329718f..1e65c081c9 100644
--- a/packages/core/src/Text/Text.test.tsx
+++ b/packages/core/src/Text/Text.test.tsx
@@ -6,7 +6,7 @@
*/
import {render, screen} from '@testing-library/react';
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
import {Text} from './Text';
import type {TextType} from './Text';
import type {TextColor} from '../theme/types';
@@ -23,6 +23,28 @@ describe('Text', () => {
expect(screen.getByText('Hello World')).toBeInTheDocument();
});
+ it('keeps a forwarded ref attached across rerenders', () => {
+ const ref = vi.fn();
+ const {rerender} = render(
+ <Text ref={ref} type="body">
+ Before
+ </Text>,
+ );
+
+ const element = screen.getByText('Before');
+ expect(ref).toHaveBeenLastCalledWith(element);
+ ref.mockClear();
+
+ rerender(
+ <Text ref={ref} type="body">
+ After
+ </Text>,
+ );
+
+ expect(ref).not.toHaveBeenCalled();
+ expect(screen.getByText('After')).toBe(element);
+ });
+
it('renders as span by default', () => {
render(<Text type="body">Text</Text>);
const element = screen.getByText('Text');
diff --git a/packages/core/src/Text/Text.tsx b/packages/core/src/Text/Text.tsx
index 4abd88d5c4..9a130df9ac 100644
--- a/packages/core/src/Text/Text.tsx
+++ b/packages/core/src/Text/Text.tsx
@@ -48,7 +48,8 @@ import {
} from './text.stylex';
import {useTruncation} from './useTruncation';
import type {LayerPlacement} from '../Layer';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
@@ -271,13 +272,16 @@ export function Text({
// Ref for the text element (used as tooltip anchor)
const textRef = useRef<HTMLElement>(null);
+ // Keep the merged ref stable across rerenders.
+ const mergedRef = useMergedRefs(ref, truncation.ref, textRef);
+
// Build inline style for -webkit-line-clamp (dynamic value)
const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;
return (
<>
<Component
- ref={mergeRefs(ref, truncation.ref, textRef)}
+ ref={mergedRef}
{...mergeProps(
themeProps('text', {type, size, color: resolvedColor}),
stylex.props(
diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.ts
index ad14642941..5796d2bb32 100644
--- a/packages/core/src/hooks/index.ts
+++ b/packages/core/src/hooks/index.ts
@@ -56,6 +56,8 @@ export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
export {useMediaQuery} from './useMediaQuery';
+export {useMergedRefs} from './useMergedRefs';
+
export {useOverflow} from './useOverflow';
export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
diff --git a/packages/core/src/hooks/useMergedRefs.doc.mjs b/packages/core/src/hooks/useMergedRefs.doc.mjs
new file mode 100644
index 0000000000..074bf37c78
--- /dev/null
+++ b/packages/core/src/hooks/useMergedRefs.doc.mjs
@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+ name: 'useMergedRefs',
+ displayName: 'useMergedRefs',
+ keywords: [
+ 'ref',
+ 'refs',
+ 'merge',
+ 'forwardRef',
+ 'callback ref',
+ 'stable ref',
+ ],
+ params: [
+ {
+ name: 'refs',
+ type: 'Array<Ref<T> | undefined>',
+ description: 'Up to six refs that should all receive the same element.',
+ required: true,
+ },
+ ],
+ returns: [
+ {
+ name: 'ref',
+ type: 'RefCallback<T>',
+ description:
+ 'A merged callback ref that remains stable until an input ref changes.',
+ },
+ ],
+ usage: {
+ description:
+ 'Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike calling mergeRefs during render, the callback identity stays stable across unrelated rerenders, so React does not detach and reattach the element.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Call mergeRefs directly in a JSX ref prop; that creates a new callback on every render and forces unnecessary detach and attach work.',
+ },
+ ],
+ },
+ relatedComponents: [],
+ relatedHooks: [],
+ importPath: '@astryxdesign/core/hooks',
+ category: 'utility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ 'Combines object/callback refs into one stable callback ref. Identity changes only when an input ref changes, avoiding detach/attach churn from inline mergeRefs calls.',
+ paramDescriptions: {
+ refs: 'refs that should all receive the same element.',
+ },
+ returnDescriptions: {
+ ref: 'stable merged callback ref; changes only when an input ref changes.',
+ },
+ usage: {
+ description:
+ 'Use when one element needs a forwarded consumer ref plus internal refs. Keeps the callback stable across unrelated rerenders.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use for a forwarded ref plus internal measurement, focus, or anchor refs.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Call mergeRefs inline in JSX; it forces ref detach/attach on every render.',
+ },
+ ],
+ },
+};
diff --git a/packages/core/src/hooks/useMergedRefs.test.tsx b/packages/core/src/hooks/useMergedRefs.test.tsx
new file mode 100644
index 0000000000..4c97f8f0d8
--- /dev/null
+++ b/packages/core/src/hooks/useMergedRefs.test.tsx
@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useMergedRefs.test.tsx
+ * @input Uses vitest, @testing-library/react, useMergedRefs hook
+ * @output Unit tests for stable merged ref behavior
+ * @position Testing; validates useMergedRefs.ts
+ *
+ * SYNC: When useMergedRefs.ts changes, update tests to match new behavior
+ */
+
+import {renderHook} from '@testing-library/react';
+import {createRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useMergedRefs} from './useMergedRefs';
+
+describe('useMergedRefs', () => {
+ it('forwards values to callback and object refs', () => {
+ const callbackRef = vi.fn();
+ const objectRef = createRef<HTMLDivElement>();
+ const {result} = renderHook(() =>
+ useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+ );
+ const element = document.createElement('div');
+
+ const cleanup = result.current(element);
+
+ expect(callbackRef).toHaveBeenCalledWith(element);
+ expect(objectRef.current).toBe(element);
+
+ cleanup?.();
+ expect(callbackRef).toHaveBeenLastCalledWith(null);
+ expect(objectRef.current).toBeNull();
+ });
+
+ it('keeps the merged callback stable when input refs are unchanged', () => {
+ const callbackRef = vi.fn();
+ const objectRef = createRef<HTMLDivElement>();
+ const {result, rerender} = renderHook(() =>
+ useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+ );
+ const first = result.current;
+
+ rerender();
+
+ expect(result.current).toBe(first);
+ });
+
+ it('updates the merged callback when an input ref changes', () => {
+ const firstRef = vi.fn();
+ const secondRef = vi.fn();
+ const {result, rerender} = renderHook(
+ ({ref}) => useMergedRefs<HTMLDivElement>(ref),
+ {initialProps: {ref: firstRef}},
+ );
+ const first = result.current;
+
+ rerender({ref: secondRef});
+
+ expect(result.current).not.toBe(first);
+ });
+});
diff --git a/packages/core/src/hooks/useMergedRefs.ts b/packages/core/src/hooks/useMergedRefs.ts
new file mode 100644
index 0000000000..c3f7ce9a83
--- /dev/null
+++ b/packages/core/src/hooks/useMergedRefs.ts
@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMergedRefs.ts
+ * @input React refs to combine into one stable callback ref
+ * @output Exports useMergedRefs
+ * @position Core hook; use when one element must receive multiple refs
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useMergedRefs.doc.mjs
+ * - /packages/core/src/hooks/useMergedRefs.test.tsx
+ */
+
+import {useMemo, type Ref, type RefCallback} from 'react';
+import {mergeRefs} from '../utils/mergeRefs';
+
+/**
+ * Combine up to six refs into a callback ref whose identity changes only when
+ * one of the input refs changes.
+ */
+export function useMergedRefs<T>(
+ refA?: Ref<T>,
+ refB?: Ref<T>,
+ refC?: Ref<T>,
+ refD?: Ref<T>,
+ refE?: Ref<T>,
+ refF?: Ref<T>,
+): RefCallback<T> {
+ return useMemo(
+ () => mergeRefs(refA, refB, refC, refD, refE, refF),
+ [refA, refB, refC, refD, refE, refF],
+ );
+}