Add *Instance type exports for all built-in components

huntie · meta-codesync[bot] · commit f0d6ab6c5bcf · 2026-06-02T10:44:38.000-07:00
Summary: Add a publicly exported `*Instance` type for every built-in component in `index.js.flow`, giving consumers a consistent way to type refs for any React Native component. Affects the Strict TypeScript API (opt-in generated TS types) only. #### Motivation + RFC Draft implementation for the recommended approach in react-native-community/discussions-and-proposals#1003. Alternative to facebook#56673. #### New types | Component | Instance Type | Type Value | |---|---|---| | `ActivityIndicator` | `ActivityIndicatorInstance` | `HostInstance` | | `Button` | `ButtonInstance` | `ButtonRef` (platform-dependent) | | `DrawerLayoutAndroid` | `DrawerLayoutAndroidInstance` | `DrawerLayoutAndroidMethods` | | `FlatList` | `FlatListInstance` | `FlatList<>` | | `Image` | `ImageInstance` | `HostInstance` | | `ImageBackground` | `ImageBackgroundInstance` | `ImageBackground` (class) | | `KeyboardAvoidingView` | `KeyboardAvoidingViewInstance` | `KeyboardAvoidingView` (class) | | `Modal` | `ModalInstance` | `HostInstance` | | `Pressable` | `PressableInstance` | `HostInstance` | | `ProgressBarAndroid` | `ProgressBarAndroidInstance` | `HostInstance` | | `RefreshControl` | `RefreshControlInstance` | `RefreshControl` (class) | | `SafeAreaView` | `SafeAreaViewInstance` | `HostInstance` | | `ScrollView` | `ScrollViewInstance` | `extends HostInstance, ScrollViewImperativeMethods` | | `SectionList` | `SectionListInstance` | `SectionList<>` | | `StatusBar` | `StatusBarInstance` | `StatusBar` (class) | | `Switch` | `SwitchInstance` | `HostInstance` | | `Text` | `TextInstance` | `HostInstance` | | `TextInput` | `TextInputInstance` | `extends ReactNativeElement` (existing) | | `TouchableHighlight` | `TouchableHighlightInstance` | `HostInstance` | | `TouchableNativeFeedback` | `TouchableNativeFeedbackInstance` | `TouchableNativeFeedback` (class) | | `TouchableOpacity` | `TouchableOpacityInstance` | `HostInstance` | | `View` | `ViewInstance` | `HostInstance` | | `VirtualizedList` | `VirtualizedListInstance` | `React.ElementRef<VirtualizedListType>` | | `VirtualizedSectionList` | `VirtualizedSectionListInstance` | `React.ElementRef<VirtualizedSectionListType>` | #### Renames - `PublicScrollViewInstance` → `ScrollViewInstance` (old name kept as deprecated alias; internal usages in `ScrollView.js` and `FlatList.js` updated) - `PublicModalInstance` → `ModalInstance` (old name kept as deprecated alias) #### Skipped (no ref support) `InputAccessoryView`, `experimental_LayoutConformance`, `TouchableWithoutFeedback`, `Touchable` (namespace) Changelog: [General][Added] - **Strict TypeScript API**: Add `*Instance` ref types for all built-in components Differential Revision: D106144383
diff --git a/packages/react-native/Libraries/Components/ActivityIndicator/ActivityIndicator.js b/packages/react-native/Libraries/Components/ActivityIndicator/ActivityIndicator.js
@@ -10,13 +10,16 @@
 
 'use strict';
 import type {HostComponent} from '../../../src/private/types/HostComponent';
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewProps} from '../View/ViewPropTypes';
 
 import StyleSheet, {type ColorValue} from '../../StyleSheet/StyleSheet';
 import Platform from '../../Utilities/Platform';
 import View from '../View/View';
 import * as React from 'react';
 
+export type ActivityIndicatorInstance = HostInstance;
+
 const PlatformActivityIndicator =
   Platform.OS === 'android'
     ? require('../ProgressBarAndroid/ProgressBarAndroid').default
diff --git a/packages/react-native/Libraries/Components/Button.js b/packages/react-native/Libraries/Components/Button.js
@@ -286,6 +286,8 @@ const NativeTouchable:
 
 type ButtonRef = React.ElementRef<typeof NativeTouchable>;
 
+export type ButtonInstance = ButtonRef;
+
 const Button: component(
   ref?: React.RefSetter<ButtonRef>,
   ...props: ButtonProps
diff --git a/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.android.js b/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.android.js
@@ -302,4 +302,6 @@ const styles = StyleSheet.create({
   },
 });
 
+export type DrawerLayoutAndroidInstance = DrawerLayoutAndroid;
+
 export default DrawerLayoutAndroid as $FlowFixMe;
diff --git a/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.ios.js b/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroid.ios.js
@@ -12,4 +12,6 @@
 
 import DrawerLayoutAndroidFallback from './DrawerLayoutAndroidFallback';
 
+export type DrawerLayoutAndroidInstance = DrawerLayoutAndroidFallback;
+
 export default DrawerLayoutAndroidFallback;
diff --git a/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroidTypes.js b/packages/react-native/Libraries/Components/DrawerAndroid/DrawerLayoutAndroidTypes.js
@@ -136,3 +136,5 @@ export interface DrawerLayoutAndroidMethods {
   ): void;
   setNativeProps(nativeProps: Object): void;
 }
+
+export type DrawerLayoutAndroidInstance = DrawerLayoutAndroidMethods;
diff --git a/packages/react-native/Libraries/Components/Keyboard/KeyboardAvoidingView.js b/packages/react-native/Libraries/Components/Keyboard/KeyboardAvoidingView.js
@@ -298,4 +298,6 @@ class KeyboardAvoidingView extends React.Component<
   }
 }
 
+export type KeyboardAvoidingViewInstance = KeyboardAvoidingView;
+
 export default KeyboardAvoidingView;
diff --git a/packages/react-native/Libraries/Components/Pressable/Pressable.js b/packages/react-native/Libraries/Components/Pressable/Pressable.js
@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewStyleProp} from '../../StyleSheet/StyleSheet';
 import type {
   GestureResponderEvent,
@@ -27,6 +28,8 @@ import useAndroidRippleForView, {
 import * as React from 'react';
 import {memo, useMemo, useRef, useState} from 'react';
 
+export type PressableInstance = HostInstance;
+
 export type {PressableAndroidRippleConfig};
 
 export type PressableStateCallbackType = Readonly<{
diff --git a/packages/react-native/Libraries/Components/ProgressBarAndroid/ProgressBarAndroid.android.js b/packages/react-native/Libraries/Components/ProgressBarAndroid/ProgressBarAndroid.android.js
@@ -8,12 +8,15 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ProgressBarAndroidProps} from './ProgressBarAndroidTypes';
 
 import ProgressBarAndroidNativeComponent from './ProgressBarAndroidNativeComponent';
 
 const React = require('react');
 
+export type ProgressBarAndroidInstance = HostInstance;
+
 export type {ProgressBarAndroidProps};
 
 /**
diff --git a/packages/react-native/Libraries/Components/ProgressBarAndroid/ProgressBarAndroid.js b/packages/react-native/Libraries/Components/ProgressBarAndroid/ProgressBarAndroid.js
@@ -10,11 +10,14 @@
 
 'use strict';
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import typeof ProgressBarAndroidNativeComponentType from './ProgressBarAndroidNativeComponent';
 import type {ProgressBarAndroidProps} from './ProgressBarAndroidTypes';
 
 import Platform from '../../Utilities/Platform';
 
+export type ProgressBarAndroidInstance = HostInstance;
+
 export type {ProgressBarAndroidProps};
 
 // A utility type to preserve the semantics of the union uses in the definition
diff --git a/packages/react-native/Libraries/Components/RefreshControl/RefreshControl.js b/packages/react-native/Libraries/Components/RefreshControl/RefreshControl.js
@@ -205,4 +205,6 @@ class RefreshControl extends React.Component<RefreshControlProps> {
   };
 }
 
+export type RefreshControlInstance = RefreshControl;
+
 export default RefreshControl;
diff --git a/packages/react-native/Libraries/Components/SafeAreaView/SafeAreaView.js b/packages/react-native/Libraries/Components/SafeAreaView/SafeAreaView.js
@@ -8,12 +8,15 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewProps} from '../View/ViewPropTypes';
 
 import Platform from '../../Utilities/Platform';
 import View from '../View/View';
 import * as React from 'react';
 
+export type SafeAreaViewInstance = HostInstance;
+
 /**
  * Renders nested content and automatically applies paddings reflect the portion
  * of the view that is not covered by navigation bars, tab bars, toolbars, and
diff --git a/packages/react-native/Libraries/Components/ScrollView/ScrollView.js b/packages/react-native/Libraries/Components/ScrollView/ScrollView.js
@@ -139,7 +139,7 @@ export interface ScrollViewImperativeMethods {
   +getScrollableNode: () => ?number;
   +getInnerViewNode: () => ?number;
   +getInnerViewRef: () => InnerViewInstance | null;
-  +getNativeScrollRef: () => PublicScrollViewInstance | null;
+  +getNativeScrollRef: () => ScrollViewInstance | null;
   +scrollTo: (
     options?: ScrollViewScrollToOptions | number,
     deprecatedX?: number,
@@ -167,10 +167,13 @@ export interface ScrollViewImperativeMethods {
 export type DecelerationRateType = 'fast' | 'normal' | number;
 export type ScrollResponderType = ScrollViewImperativeMethods;
 
-export interface PublicScrollViewInstance
+export interface ScrollViewInstance
   extends HostInstance,
     ScrollViewImperativeMethods {}
 
+/** @deprecated Use ScrollViewInstance instead */
+export type PublicScrollViewInstance = ScrollViewInstance;
+
 type InnerViewInstance = React.ElementRef<typeof View>;
 
 export type ScrollViewPropsIOS = Readonly<{
@@ -677,7 +680,7 @@ type ScrollViewBaseProps = Readonly<{
    * all of ScrollView's public methods, in addition to native methods like
    * measure, measureLayout, etc.
    */
-  scrollViewRef?: React.RefSetter<PublicScrollViewInstance>,
+  scrollViewRef?: React.RefSetter<ScrollViewInstance>,
 }>;
 
 /** @build-types emit-as-interface Nativewind compatibility */
@@ -874,7 +877,7 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
   getNativeScrollRef: ScrollViewImperativeMethods['getNativeScrollRef'] =
     () => {
       // Object.assign in _scrollView's mutator augments nativeInstance in place,
-      // so it is already a PublicScrollViewInstance at runtime.
+      // so it is already a ScrollViewInstance at runtime.
       // $FlowFixMe[incompatible-type]
       return this._scrollView.nativeInstance;
     };
@@ -1170,7 +1173,7 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
       (instance: InnerViewInstance): InnerViewInstance => instance,
     );
 
-  _scrollView: RefForwarder<HostInstance, PublicScrollViewInstance | null> =
+  _scrollView: RefForwarder<HostInstance, ScrollViewInstance | null> =
     createRefForwarder(nativeInstance => {
       // This is a hack. Ideally we would forwardRef  to the underlying
       // host component. However, since ScrollView has it's own methods that can be
@@ -1183,22 +1186,19 @@ class ScrollView extends React.Component<ScrollViewProps, ScrollViewState> {
       // $FlowFixMe[prop-missing] - Known issue with appending custom methods.
       // $FlowFixMe[incompatible-type]
       // $FlowFixMe[unsafe-object-assign]
-      const publicInstance: PublicScrollViewInstance = Object.assign(
-        nativeInstance,
-        {
-          getScrollResponder: this.getScrollResponder,
-          getScrollableNode: this.getScrollableNode,
-          getInnerViewNode: this.getInnerViewNode,
-          getInnerViewRef: this.getInnerViewRef,
-          getNativeScrollRef: this.getNativeScrollRef,
-          scrollTo: this.scrollTo,
-          scrollToEnd: this.scrollToEnd,
-          flashScrollIndicators: this.flashScrollIndicators,
-          scrollResponderZoomTo: this.scrollResponderZoomTo,
-          scrollResponderScrollNativeHandleToKeyboard:
-            this.scrollResponderScrollNativeHandleToKeyboard,
-        },
-      );
+      const publicInstance: ScrollViewInstance = Object.assign(nativeInstance, {
+        getScrollResponder: this.getScrollResponder,
+        getScrollableNode: this.getScrollableNode,
+        getInnerViewNode: this.getInnerViewNode,
+        getInnerViewRef: this.getInnerViewRef,
+        getNativeScrollRef: this.getNativeScrollRef,
+        scrollTo: this.scrollTo,
+        scrollToEnd: this.scrollToEnd,
+        flashScrollIndicators: this.flashScrollIndicators,
+        scrollResponderZoomTo: this.scrollResponderZoomTo,
+        scrollResponderScrollNativeHandleToKeyboard:
+          this.scrollResponderScrollNativeHandleToKeyboard,
+      });
 
       return publicInstance;
     });
@@ -1935,13 +1935,13 @@ function createRefForwarder<TNativeInstance, TPublicInstance>(
 // component and we need to map `ref` to a differently named prop. This can be
 // removed when `ScrollView` is a functional component.
 const ScrollViewWrapper: component(
-  ref?: React.RefSetter<PublicScrollViewInstance>,
+  ref?: React.RefSetter<ScrollViewInstance>,
   ...props: ScrollViewProps
 ) = function Wrapper({
   ref,
   ...props
 }: {
-  ref?: React.RefSetter<PublicScrollViewInstance>,
+  ref?: React.RefSetter<ScrollViewInstance>,
   ...ScrollViewProps,
 }): React.Node {
   return ref == null ? (
diff --git a/packages/react-native/Libraries/Components/StatusBar/StatusBar.js b/packages/react-native/Libraries/Components/StatusBar/StatusBar.js
@@ -561,4 +561,6 @@ class StatusBar extends React.Component<StatusBarProps> {
   }
 }
 
+export type StatusBarInstance = StatusBar;
+
 export default StatusBar;
diff --git a/packages/react-native/Libraries/Components/Switch/Switch.js b/packages/react-native/Libraries/Components/Switch/Switch.js
@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ColorValue} from '../../StyleSheet/StyleSheet';
 import type {NativeSyntheticEvent} from '../../Types/CoreEventTypes';
 import type {AccessibilityState} from '../View/ViewAccessibility';
@@ -25,6 +26,8 @@ import SwitchNativeComponent, {
 import * as React from 'react';
 import {useLayoutEffect, useRef, useState} from 'react';
 
+export type SwitchInstance = HostInstance;
+
 export type SwitchPropsIOS = {
   /**
    * Background color when the switch is turned on.
diff --git a/packages/react-native/Libraries/Components/TextInput/TextInput.js b/packages/react-native/Libraries/Components/TextInput/TextInput.js
@@ -117,6 +117,7 @@ export type {
   TextInputKeyPressEvent,
   TextInputProps,
   TextInputSelectionChangeEvent,
+  TextInputInstance,
   TextInputSubmitEditingEvent,
 };
 
diff --git a/packages/react-native/Libraries/Components/Touchable/TouchableHighlight.js b/packages/react-native/Libraries/Components/Touchable/TouchableHighlight.js
@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ColorValue} from '../../StyleSheet/StyleSheet';
 import type {AccessibilityState} from '../View/ViewAccessibility';
 import type {TouchableWithoutFeedbackProps} from './TouchableWithoutFeedback';
@@ -23,6 +24,8 @@ import warnOnce from '../../Utilities/warnOnce';
 import * as React from 'react';
 import {cloneElement} from 'react';
 
+export type TouchableHighlightInstance = HostInstance;
+
 type AndroidProps = Readonly<{
   nextFocusDown?: ?number,
   nextFocusForward?: ?number,
diff --git a/packages/react-native/Libraries/Components/Touchable/TouchableNativeFeedback.js b/packages/react-native/Libraries/Components/Touchable/TouchableNativeFeedback.js
@@ -409,4 +409,6 @@ const getBackgroundProp =
 
 TouchableNativeFeedback.displayName = 'TouchableNativeFeedback';
 
+export type TouchableNativeFeedbackInstance = TouchableNativeFeedback;
+
 export default TouchableNativeFeedback;
diff --git a/packages/react-native/Libraries/Components/Touchable/TouchableOpacity.js b/packages/react-native/Libraries/Components/Touchable/TouchableOpacity.js
@@ -8,6 +8,7 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewStyleProp} from '../../StyleSheet/StyleSheet';
 import type {TouchableWithoutFeedbackProps} from './TouchableWithoutFeedback';
 
@@ -21,6 +22,8 @@ import flattenStyle from '../../StyleSheet/flattenStyle';
 import Platform from '../../Utilities/Platform';
 import * as React from 'react';
 
+export type TouchableOpacityInstance = HostInstance;
+
 export type TouchableOpacityTVProps = Readonly<{
   /**
    * *(Apple TV only)* TV preferred focus (see documentation for the View component).
diff --git a/packages/react-native/Libraries/Components/View/View.js b/packages/react-native/Libraries/Components/View/View.js
@@ -8,13 +8,16 @@
  * @format
  */
 
+import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewProps} from './ViewPropTypes';
 
 import TextAncestorContext from '../../Text/TextAncestorContext';
 import ViewNativeComponent from './ViewNativeComponent';
 import * as React from 'react';
 import {use} from 'react';
 
+export type ViewInstance = HostInstance;
+
 /**
  * The most fundamental component for building a UI, View is a container that
  * supports layout with flexbox, style, some touch handling, and accessibility
diff --git a/packages/react-native/Libraries/Image/Image.android.js b/packages/react-native/Libraries/Image/Image.android.js
@@ -31,6 +31,8 @@ import resolveAssetSource from './resolveAssetSource';
 import * as React from 'react';
 import {use} from 'react';
 
+export type ImageInstance = HostInstance;
+
 let _requestId = 1;
 function generateRequestId() {
   return _requestId++;
diff --git a/packages/react-native/Libraries/Image/Image.ios.js b/packages/react-native/Libraries/Image/Image.ios.js
@@ -30,6 +30,8 @@ import NativeImageLoaderIOS from './NativeImageLoaderIOS';
 import resolveAssetSource from './resolveAssetSource';
 import * as React from 'react';
 
+export type ImageInstance = HostInstance;
+
 function getSize(
   uri: string,
   success?: (width: number, height: number) => void,
diff --git a/packages/react-native/Libraries/Image/ImageBackground.js b/packages/react-native/Libraries/Image/ImageBackground.js
@@ -105,4 +105,6 @@ class ImageBackground extends React.Component<ImageBackgroundProps> {
   }
 }
 
+export type ImageBackgroundInstance = ImageBackground;
+
 export default ImageBackground;
diff --git a/packages/react-native/Libraries/Image/ImageTypes.flow.js b/packages/react-native/Libraries/Image/ImageTypes.flow.js
@@ -16,6 +16,8 @@ import type {ImageSource} from './ImageSource';
 
 import * as React from 'react';
 
+export type ImageInstance = HostInstance;
+
 export type ImageSize = {
   width: number,
   height: number,
diff --git a/packages/react-native/Libraries/Lists/FlatList.js b/packages/react-native/Libraries/Lists/FlatList.js
@@ -8,7 +8,7 @@
  * @format
  */
 
-import type {PublicScrollViewInstance} from '../Components/ScrollView/ScrollView';
+import type {ScrollViewInstance} from '../Components/ScrollView/ScrollView';
 import type {ViewStyleProp} from '../StyleSheet/StyleSheet';
 import type {
   ListRenderItem,
@@ -398,7 +398,7 @@ class FlatList<ItemT = any> extends React.PureComponent<FlatListProps<ItemT>> {
   /**
    * Provides a reference to the underlying host component
    */
-  getNativeScrollRef(): ?PublicScrollViewInstance {
+  getNativeScrollRef(): ?ScrollViewInstance {
     if (this._listRef) {
       return this._listRef.getScrollRef();
     }
@@ -706,4 +706,6 @@ const styles = StyleSheet.create({
   row: {flexDirection: 'row'},
 });
 
+export type FlatListInstance = FlatList<>;
+
 export default FlatList;
diff --git a/packages/react-native/Libraries/Lists/SectionList.js b/packages/react-native/Libraries/Lists/SectionList.js
@@ -265,3 +265,5 @@ export default class SectionList<
     this._wrapperListRef = ref;
   };
 }
+
+export type SectionListInstance = SectionList<>;
diff --git a/packages/react-native/Libraries/Lists/VirtualizedList.js b/packages/react-native/Libraries/Lists/VirtualizedList.js
@@ -11,11 +11,14 @@
 'use strict';
 
 import VirtualizedLists from '@react-native/virtualized-lists';
+import * as React from 'react';
 
 type VirtualizedListType = typeof VirtualizedLists.VirtualizedList;
 const VirtualizedListComponent: VirtualizedListType =
   VirtualizedLists.VirtualizedList;
 
+export type VirtualizedListInstance = React.ElementRef<VirtualizedListType>;
+
 export type {
   ListRenderItemInfo,
   ListRenderItem,
diff --git a/packages/react-native/Libraries/Lists/VirtualizedSectionList.js b/packages/react-native/Libraries/Lists/VirtualizedSectionList.js
diff --git a/packages/react-native/Libraries/Modal/Modal.js b/packages/react-native/Libraries/Modal/Modal.js
diff --git a/packages/react-native/Libraries/Text/Text.js b/packages/react-native/Libraries/Text/Text.js
diff --git a/packages/react-native/ReactNativeApi.d.ts b/packages/react-native/ReactNativeApi.d.ts
diff --git a/packages/react-native/index.js.flow b/packages/react-native/index.js.flow
diff --git a/packages/react-native/src/private/types/HostInstance.js b/packages/react-native/src/private/types/HostInstance.js

Original file line number	Diff line number	Diff line change
`@@ -136,3 +136,5 @@ export interface DrawerLayoutAndroidMethods {`
`136`	`136`	`): void;`
`137`	`137`	`setNativeProps(nativeProps: Object): void;`
`138`	`138`	`}`
	`139`	`+`
	`140`	`+export type DrawerLayoutAndroidInstance = DrawerLayoutAndroidMethods;`
Original file line number	Diff line number	Diff line change
`@@ -298,4 +298,6 @@ class KeyboardAvoidingView extends React.Component<`
`298`	`298`	`}`
`299`	`299`	`}`
`300`	`300`
	`301`	`+export type KeyboardAvoidingViewInstance = KeyboardAvoidingView;`
	`302`	`+`
`301`	`303`	`export default KeyboardAvoidingView;`
Original file line number	Diff line number	Diff line change
`@@ -205,4 +205,6 @@ class RefreshControl extends React.Component<RefreshControlProps> {`
`205`	`205`	`};`
`206`	`206`	`}`
`207`	`207`
	`208`	`+export type RefreshControlInstance = RefreshControl;`
	`209`	`+`
`208`	`210`	`export default RefreshControl;`