Skip to main content
AppRegistry is the JS entry point to running all React Native apps. App root components should register themselves with AppRegistry.registerComponent, then the native system can load the bundle for the app and run it when ready by invoking AppRegistry.runApplication.

​
Methods

​
registerComponent()

static registerComponent(
  appKey: string,
  componentProvider: () => React.ComponentType<any>,
  section?: boolean
): string
Registers an app’s root component. This is the main method you’ll use in your app’s entry file. Parameters:
  • appKey: String name for the application
  • componentProvider: Function that returns a React component
  • section: Optional boolean to register as a section
Returns:
  • The appKey that was registered
Example: 
import { AppRegistry } from 'react-native';
import App from './App';

AppRegistry.registerComponent('MyApp', () => App);

​
runApplication()

static runApplication(
  appKey: string,
  appParameters: any,
  displayMode?: number
): void
Loads the JavaScript bundle and runs the app. Usually called from native code. Parameters:
  • appKey: The string name of the app to run
  • appParameters: Object containing:
    • initialProps: Props to pass to the root component
    • rootTag: The native root view tag
    • fabric: Whether Fabric renderer is enabled
  • displayMode: Optional display mode configuration
Example: 
import { AppRegistry } from 'react-native';

AppRegistry.runApplication('MyApp', {
  initialProps: { userId: '123' },
  rootTag: 1,
});

​
unmountApplicationComponentAtRootTag()

static unmountApplicationComponentAtRootTag(rootTag: number): void
Stops an application when a view should be destroyed. Should be used as a pair with runApplication. Parameters:
  • rootTag: The root tag that was passed to runApplication
Example: 
import { AppRegistry } from 'react-native';

AppRegistry.unmountApplicationComponentAtRootTag(1);

​
registerHeadlessTask()

static registerHeadlessTask(
  taskKey: string,
  taskProvider: () => (taskData: any) => Promise<void>
): void
Register a headless task - code that runs without a UI (e.g., handling push notifications in the background). Parameters:
  • taskKey: Unique string identifier for the task
  • taskProvider: Function that returns an async task function
Example: 
import { AppRegistry } from 'react-native';

const MyTask = async (taskData) => {
  console.log('Headless task running with data:', taskData);
  // Perform background work
};

AppRegistry.registerHeadlessTask('MyTask', () => MyTask);

​
registerCancellableHeadlessTask()

static registerCancellableHeadlessTask(
  taskKey: string,
  taskProvider: () => (taskData: any) => Promise<void>,
  taskCancelProvider: () => () => void
): void
Register a cancellable headless task that can be stopped mid-execution. Parameters:
  • taskKey: Unique string identifier for the task
  • taskProvider: Function that returns an async task function
  • taskCancelProvider: Function that returns a cancellation function
Example: 
import { AppRegistry } from 'react-native';

let taskCancelled = false;

const MyTask = async (taskData) => {
  for (let i = 0; i < 100; i++) {
    if (taskCancelled) break;
    // Do work
  }
};

AppRegistry.registerCancellableHeadlessTask(
  'MyCancellableTask',
  () => MyTask,
  () => () => { taskCancelled = true; }
);

​
startHeadlessTask()

static startHeadlessTask(
  taskId: number,
  taskKey: string,
  data: any
): void
Starts a headless task. Only called from native code. Parameters:
  • taskId: Numeric ID for this task instance
  • taskKey: The registered task key
  • data: Data to pass to the task

​
cancelHeadlessTask()

static cancelHeadlessTask(
  taskId: number,
  taskKey: string
): void
Cancels a running headless task. Only called from native code. Parameters:
  • taskId: The task instance ID
  • taskKey: The registered task key

​
setSurfaceProps()

static setSurfaceProps(
  appKey: string,
  appParameters: any,
  displayMode?: number
): void
Updates initial props for a surface that’s already rendered. Parameters:
  • appKey: The registered app key
  • appParameters: New parameters/props
  • displayMode: Optional display mode

​
getAppKeys()

static getAppKeys(): string[]
Returns an array of all registered app keys. Returns:
  • Array of registered application keys

​
getRunnable()

static getRunnable(appKey: string): Runnable | undefined
Gets the runnable function for a registered app. Parameters:
  • appKey: The app key to look up
Returns:
  • The runnable function or undefined if not found

​
Typical Usage

In your app’s entry file (usually index.js): 
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';

AppRegistry.registerComponent(appName, () => App);

Build docs developers (and LLMs) love

Get started for freeTalk to us