@samitouri / QOS-React / commits / a4eb2dfa6f

Release Fragment refs to Canary (#34720)

## Overview This PR adds the `ref` prop to `<Fragment>` in `react@canary`. This means this API is ready for final feedback and prepared for a semver stable release. ## What this means Shipping Fragment refs to canary means they have gone through extensive testing in production, we are confident in the stability of the APIs, and we are preparing to release it in a future semver stable version. Libraries and frameworks following the [Canary Workflow](https://react.dev/blog/2023/05/03/react-canaries) should begin implementing and testing these features. ## Why we follow the Canary Workflow To prepare for semver stable, libraries should test canary features like Fragment refs with `react@canary` to confirm compatibility and prepare for the next semver release in a myriad of environments and configurations used throughout the React ecosystem. This provides libraries with ample time to catch any issues we missed before slamming them with problems in the wider semver release. Since these features have already gone through extensive production testing, and we are confident they are stable, frameworks following the [Canary Workflow](https://react.dev/blog/2023/05/03/react-canaries) can also begin adopting canary features like Fragment refs. This adoption is similar to how different Browsers implement new proposed browser features before they are added to the standard. If a frameworks adopts a canary feature, they are committing to stability for their users by ensuring any API changes before a semver stable release are opaque and non-breaking to their users. Apps not using a framework are also free to adopt canary features like Fragment refs as long as they follow the [Canary Workflow](https://react.dev/blog/2023/05/03/react-canaries), but we generally recommend waiting for a semver stable release unless you have the capacity to commit to following along with the canary changes and debugging library compatibility issues. Waiting for semver stable means you're able to benefit from libraries testing and confirming support, and use semver as signal for which version of a library you can use with support of the feature. ## Docs Check out the ["React Labs: View Transitions, Activity, and more"](https://react.dev/blog/2025/04/23/react-labs-view-transitions-activity-and-more#fragment-refs) blog post, and [the new docs for Fragment refs`](https://react.dev/reference/react/Fragment#fragmentinstance) for more info.

Sebastian "Sebbie" Silbermann committed Oct 7, 2025 at 06:24 UTC a4eb2dfa6fec3da5a947eb84c99b059890bb5241

7 files changed +22 -22

fixtures/dom/src/components/fixtures/fragment-refs/ScrollIntoViewCase.js

+2 -2

@@ -55,11 +55,11 @@ export default function ScrollIntoViewCase() {

55 const scrollContainerRef = useRef(null);

57 const scrollVertical = () => {

58 - fragmentRef.current.experimental_scrollIntoView(alignToTop);

58 + fragmentRef.current.scrollIntoView(alignToTop);

59 };

61 const scrollVerticalNoChildren = () => {

62 - noChildRef.current.experimental_scrollIntoView(alignToTop);

62 + noChildRef.current.scrollIntoView(alignToTop);

63 };

65 useEffect(() => {

packages/react-dom-bindings/src/client/ReactFiberConfigDOM.js

+2 -2

@@ -3341,13 +3341,13 @@ function validateDocumentPositionWithFiberTree(

3341

3342 if (enableFragmentRefsScrollIntoView) {

3343 // $FlowFixMe[prop-missing]

3344 - FragmentInstance.prototype.experimental_scrollIntoView = function (

3344 + FragmentInstance.prototype.scrollIntoView = function (

3345 this: FragmentInstanceType,

3346 alignToTop?: boolean,

3347 ): void {

3348 if (typeof alignToTop === 'object') {

3349 throw new Error(

3350 - 'FragmentInstance.experimental_scrollIntoView() does not support ' +

3350 + 'FragmentInstance.scrollIntoView() does not support ' +

3351 'scrollIntoViewOptions. Use the alignToTop boolean instead.',

3352 );

3353 }

packages/react-dom/src/__tests__/ReactDOMFragmentRefs-test.js

+12 -12

@@ -1960,9 +1960,9 @@ describe('FragmentRefs', () => {

1960 });

1961

1962 expect(() => {

1963 - fragmentRef.current.experimental_scrollIntoView({block: 'start'});

1963 + fragmentRef.current.scrollIntoView({block: 'start'});

1964 }).toThrowError(

1965 - 'FragmentInstance.experimental_scrollIntoView() does not support ' +

1965 + 'FragmentInstance.scrollIntoView() does not support ' +

1966 'scrollIntoViewOptions. Use the alignToTop boolean instead.',

1967 );

1968 });

@@ -1996,11 +1996,11 @@ describe('FragmentRefs', () => {

1996 });

1997

1998 // Default call

1999 - fragmentRef.current.experimental_scrollIntoView();

1999 + fragmentRef.current.scrollIntoView();

2000 expectLast(logs, 'childA');

2001 logs = [];

2002 // alignToTop=true

2003 - fragmentRef.current.experimental_scrollIntoView(true);

2003 + fragmentRef.current.scrollIntoView(true);

2004 expectLast(logs, 'childA');

2005 });

2006

@@ -2027,7 +2027,7 @@ describe('FragmentRefs', () => {

2027 logs.push('childB');

2028 });

2029

2030 - fragmentRef.current.experimental_scrollIntoView(false);

2030 + fragmentRef.current.scrollIntoView(false);

2031 expectLast(logs, 'childB');

2032 });

2033

@@ -2068,7 +2068,7 @@ describe('FragmentRefs', () => {

2068 });

2069

2070 // Default call

2071 - fragmentRef.current.experimental_scrollIntoView();

2071 + fragmentRef.current.scrollIntoView();

2072 expectLast(logs, 'childA');

2073 });

2074

@@ -2157,7 +2157,7 @@ describe('FragmentRefs', () => {

2157 });

2158

2159 // Default call

2160 - fragmentRef.current.experimental_scrollIntoView();

2160 + fragmentRef.current.scrollIntoView();

2161 expectLast(logs, 'header');

2162

2163 childARef.current.scrollIntoView.mockClear();

@@ -2167,7 +2167,7 @@ describe('FragmentRefs', () => {

2167 logs = [];

2168

2169 // // alignToTop=false

2170 - fragmentRef.current.experimental_scrollIntoView(false);

2170 + fragmentRef.current.scrollIntoView(false);

2171 expectLast(logs, 'C');

2172 });

2173 });

@@ -2195,14 +2195,14 @@ describe('FragmentRefs', () => {

2195 siblingBRef.current.scrollIntoView = jest.fn();

2196

2197 // Default call

2198 - fragmentRef.current.experimental_scrollIntoView();

2198 + fragmentRef.current.scrollIntoView();

2199 expect(siblingARef.current.scrollIntoView).toHaveBeenCalledTimes(0);

2200 expect(siblingBRef.current.scrollIntoView).toHaveBeenCalledTimes(1);

2201

2202 siblingBRef.current.scrollIntoView.mockClear();

2203

2204 // alignToTop=true

2205 - fragmentRef.current.experimental_scrollIntoView(true);

2205 + fragmentRef.current.scrollIntoView(true);

2206 expect(siblingARef.current.scrollIntoView).toHaveBeenCalledTimes(0);

2207 expect(siblingBRef.current.scrollIntoView).toHaveBeenCalledTimes(1);

2208 });

@@ -2239,7 +2239,7 @@ describe('FragmentRefs', () => {

2239 siblingBRef.current.scrollIntoView = jest.fn();

2240

2241 // alignToTop=false

2242 - fragmentRef.current.experimental_scrollIntoView(false);

2242 + fragmentRef.current.scrollIntoView(false);

2243 expect(siblingARef.current.scrollIntoView).toHaveBeenCalledTimes(1);

2244 expect(siblingBRef.current.scrollIntoView).toHaveBeenCalledTimes(0);

2245 });

@@ -2260,7 +2260,7 @@ describe('FragmentRefs', () => {

2260 });

2261

2262 parentRef.current.scrollIntoView = jest.fn();

2263 - fragmentRef.current.experimental_scrollIntoView();

2263 + fragmentRef.current.scrollIntoView();

2264 expect(parentRef.current.scrollIntoView).toHaveBeenCalledTimes(1);

2265 });

2266 });

packages/shared/ReactFeatureFlags.js

+2 -2

@@ -145,8 +145,8 @@ export const transitionLaneExpirationMs = 5000;

145 */

146 export const enableInfiniteRenderLoopDetection: boolean = false;

147

148 -export const enableFragmentRefs = __EXPERIMENTAL__;

149 -export const enableFragmentRefsScrollIntoView = __EXPERIMENTAL__;

148 +export const enableFragmentRefs: boolean = true;

149 +export const enableFragmentRefsScrollIntoView: boolean = true;

150

151 // -----------------------------------------------------------------------------

152 // Ready for next major.

packages/shared/forks/ReactFeatureFlags.native-oss.js

+1 -1

@@ -72,7 +72,7 @@ export const enableHydrationChangeEvent: boolean = false;

72 export const enableDefaultTransitionIndicator: boolean = false;

73 export const ownerStackLimit = 1e4;

75 -export const enableFragmentRefs: boolean = false;

75 +export const enableFragmentRefs: boolean = true;

76 export const enableFragmentRefsScrollIntoView: boolean = false;

78 // Profiling Only

packages/shared/forks/ReactFeatureFlags.test-renderer.js

+2 -2

@@ -73,8 +73,8 @@ export const enableHydrationChangeEvent: boolean = false;

73 export const enableDefaultTransitionIndicator: boolean = false;

74 export const ownerStackLimit = 1e4;

76 -export const enableFragmentRefs: boolean = false;

77 -export const enableFragmentRefsScrollIntoView: boolean = false;

76 +export const enableFragmentRefs: boolean = true;

77 +export const enableFragmentRefsScrollIntoView: boolean = true;

79 // TODO: This must be in sync with the main ReactFeatureFlags file because

80 // the Test Renderer's value must be the same as the one used by the

scripts/error-codes/codes.json

+1 -1

@@ -551,5 +551,5 @@

551 "563": "This render completed successfully. All cacheSignals are now aborted to allow clean up of any unused resources.",

552 "564": "Unknown command. The debugChannel was not wired up properly.",

553 "565": "resolveDebugMessage/closeDebugChannel should not be called for a Request that wasn't kept alive. This is a bug in React.",

554 - "566": "FragmentInstance.experimental_scrollIntoView() does not support scrollIntoViewOptions. Use the alignToTop boolean instead."

554 + "566": "FragmentInstance.scrollIntoView() does not support scrollIntoViewOptions. Use the alignToTop boolean instead."

555 }