RootTag

RootTag is an opaque identifier assigned to the native root view of a React Native surface — a single mounted React tree. On Vega, each registered application component (a window/surface, identified by the moduleName it was registered with in the AppRegistry) has its own RootTag; on Android and iOS it corresponds to the ReactRootView or RCTRootView instance respectively. In short, it is a surface identifier.

When to use a RootTag?

For most VegaScript developers, you likely won't need to deal with RootTags.

RootTags are useful when an app renders multiple React Native root views and you need to handle native API calls differently depending on the surface. An example is an app using native navigation where each screen is a separate React Native root view. On Vega, this is also the case when an application registers more than one component window/surface — each is a separate root view with its own RootTag, which is why useKeplerWindowDimensionsV2 is keyed by root tag.

In native navigation, every React Native root view is rendered in a platform's navigation view (e.g., Activity for Android, UINavigationViewController for iOS). By this, you are able to leverage the navigation paradigms of the platform such as native look and feel and navigation transitions. The functionality to interact with the native navigation APIs can be exposed to React Native via a native module.

For example, to update the title bar of a screen, you would call the navigation module's API setTitle("Updated Title"), but it would need to know which screen in the stack to update. A RootTag is necessary here to identify the root view and its hosting container.

Another use case for RootTag is when your app needs to attribute a certain JavaScript call to native based on its originating root view. A RootTag is necessary to differentiate the source of the call from different surfaces.

How to access the RootTag… if you need it

React Native exposes the current surface's RootTag through RootTagContext, a React Context. The runtime sets the context value for you (via AppContainer), so any component in the tree can read it without you creating the provider or drilling the value down through props.

Access it with the useContext hook in function components, or static contextType in class components:

import {RootTagContext} from 'react-native';
import NativeAnalytics from 'native-analytics';
import NativeNavigation from 'native-navigation';

function ScreenA() {
  const rootTag = useContext(RootTagContext);

  const updateTitle = title => {
    NativeNavigation.setTitle(rootTag, title);
  };

  const handleOneEvent = () => {
    NativeAnalytics.logEvent(rootTag, 'one_event');
  };

  // ...
}

class ScreenB extends React.Component {
  static contextType: typeof RootTagContext = RootTagContext;

  updateTitle(title) {
    NativeNavigation.setTitle(this.context, title);
  }

  handleOneEvent() {
    NativeAnalytics.logEvent(this.context, 'one_event');
  }

  // ...
}

Learn more about the Context API for classes and hooks from the React docs.

Future Plans

With the evolving React Native architecture, there may be future iterations to RootTag, with the intention to keep the RootTag type opaque and prevent thrash in codebases. Please do not rely on the fact that RootTag currently aliases to a number! If your app relies on RootTags, keep an eye on the React Native change logs.

Last updated: Jul 23, 2026