react-native-orientation-locker

Install the module using yarn based on your React Native version.

For RN 0.60 and above:

yarn add react-native-orientation-locker

For RN 0.59 and below:

yarn add react-native-orientation-locker
react-native link react-native-orientation-locker

The OrientationLocker component uses an internal stack to manage orientation requests.

1. Mounting: When a component with <OrientationLocker> mounts, its requested orientation is pushed onto a global stack.
2. Resolution: The library iterates through the stack from the most recent entry to the oldest. The first non-empty orientation found in the stack is applied to the device.
3. Unmounting: When a component unmounts, it is removed from the stack, and the library re-evaluates the stack to apply the next available orientation.

This pattern ensures that if a specific screen requires LANDSCAPE, the device will return to its previous orientation (e.g., PORTRAIT) automatically once that screen is closed.

iOS

• Library not found error: If you see ld: library not found for -lRCTOrientation-tvOS, remove it from your linked libraries and frameworks.
• iPad Delay: orientationDidChange may be delayed on iPads if upside down is enabled. Disable upside down for iPad to resolve this.

Android

• Fullscreen Requirement: If you encounter java.lang.IllegalStateException: Only fullscreen activities can request orientation, ensure your activity is set to fullscreen.

Windows

• Locking: Locking to an orientation only works on devices in tablet mode.
• Sensors: getDeviceOrientation() will return UNKNOWN if the device lacks an orientation sensor.

Use these methods to query the current state of the device or the library's lock status.

• getOrientation(callback): Retrieves the current UI orientation via a callback.
• getDeviceOrientation(callback): Retrieves the current physical device orientation via a callback.
• getAutoRotateState(callback): Android only. Retrieves the auto-rotate state.
• isLocked(): Returns a boolean indicating if the orientation is currently locked by this library.

OrientationLocker.getOrientation((orientation) => {
  console.log("Current orientation: ", orientation);
});

if (OrientationLocker.isLocked()) {
  console.log("Orientation is locked");
}

To remove all active orientation, device orientation, and lock listeners at once, use removeAllListeners().

OrientationLocker.removeAllListeners();

Use built-in hooks to respond to orientation changes within functional components.

• useOrientationChange(callback): Hook for addOrientationListener events (UI orientation).
• useDeviceOrientationChange(callback): Hook for addDeviceOrientationListener events (Physical device orientation).

function SomeComponent() {
  useOrientationChange((o) => {
    // Handle orientation change
  });

  useDeviceOrientationChange((o) => {
    // Handle device orientation change
  });
}

The <OrientationLocker> component allows you to declaratively manage orientation. Multiple components can be mounted; their props are merged in the order they were mounted, similar to the <StatusBar> component.

Props:

• orientation: The desired orientation (e.g., PORTRAIT, LANDSCAPE).
• onChange: Callback triggered when the UI orientation changes.
• onDeviceChange: Callback triggered when the device orientation changes.

import React, { useState } from "react";
import { OrientationLocker, PORTRAIT, LANDSCAPE } from "react-native-orientation-locker";

export default function App() {
  return (
    <OrientationLocker
      orientation={PORTRAIT}
      onChange={orientation => console.log('onChange', orientation)}
      onDeviceChange={orientation => console.log('onDeviceChange', orientation)}
    />
  );
}

On iOS, you can use configure to adjust orientation behavior.

• configure({ disableFaceUpDown: boolean }): If set to true, prevents certain face-up/face-down behaviors.

// iOS only
OrientationLocker.configure({ disableFaceUpDown: true });

Use addDeviceOrientationListener to track the physical orientation of the device. Unlike UI orientation, this callback can still be called even when lockToXXX is active.

Possible return values:

• PORTRAIT
• LANDSCAPE-LEFT
• LANDSCAPE-RIGHT
• PORTRAIT-UPSIDEDOWN
• UNKNOWN

const deviceListener = OrientationLocker.addDeviceOrientationListener((deviceOrientation) => {
  console.log("Device Orientation changed: ", deviceOrientation);
});

// To stop listening:
OrientationLocker.removeDeviceOrientationListener(deviceListener);

You can subscribe to UI orientation changes using addOrientationListener. Note that if you use lockToXXX methods, the callback will not be triggered until unlockAllOrientations is called. The listener will force a resend of the event when locking or unlocking orientations.

Possible return values:

• PORTRAIT
• LANDSCAPE-LEFT
• LANDSCAPE-RIGHT
• PORTRAIT-UPSIDEDOWN
• UNKNOWN

const orientationListener = OrientationLocker.addOrientationListener((orientation) => {
  console.log("UI Orientation changed: ", orientation);
});

// To stop listening:
OrientationLocker.removeOrientationListener(orientationListener);