# react-native-orientation-locker: locking screen orientation across iOS, Android and Windows > react-native-orientation-locker is a React Native module that locks the UI orientation, reports the current orientation, and fires a listener when the device orientation changes, with native implementations for iOS, Android and Windows. The iOS path requires edits to the AppDelegate and a bridging header, and the Android path expects a lifecycle callback registered in your MainApplication. **wonday/react-native-orientation-locker** — A react-native module that can listen on orientation changing of device, get current orientation, lock to preferred orientation. - Repository: https://github.com/wonday/react-native-orientation-locker - Stars: 805 · Forks: 293 - Language: JavaScript - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/wonday-react-native-orientation-locker ## Three things the module does react-native-orientation-locker is a React Native module that can listen to orientation changes of the device, get the current orientation, and lock to a preferred orientation, with cross-platform support. The feature list is short enough to state exactly. It can lock the screen orientation to one of the four platform values, portrait, portrait upside down or either side-on direction. It can listen for orientation changing. And it can report the current orientation of the device. The API surface grew in a way that reveals what the author found in practice. Version 1.1.0 was a breaking release that split a single orientation listener into two, addOrientationListener taking a function of orientation and addDeviceOrientationListener taking a function of deviceOrientation, and added getAutoRotateState() for Android. That split exists because the UI orientation and the physical device orientation are different things, and a listener that conflates them gives you the wrong value on a device that is locked but being turned. Two related additions came later: addLockListener and removeLockListener in 1.1.3, and Orientation.isLocked() plus Orientation.removeAllListeners() in 1.1.5. The second of those pairs matters for a component that unmounts, since a listener left registered fires into a dead component. The package is MIT licensed, the main entry point is index.js with TypeScript declarations in index.d.ts, and the repository carries native source directories for android, iOS and windows alongside an example project. ## Installing it and the autolinking split On React Native 0.60 and above, autolinking handles the native side, so the install is a single package add: ``` yarn add react-native-orientation-locker ``` On React Native 0.59 and below, the module also has to be linked explicitly: ``` yarn add react-native-orientation-locker react-native link react-native-orientation-locker ``` For iOS, the documentation says to run pod install in the ios directory, and notes that linking is not required in React Native 0.60 and above. For Windows, autolinking covers React Native Windows 0.63.0 and higher, and older versions need the manual native module linking steps from the React Native Windows documentation. The peer dependencies in the package manifest set the floor. React has to be 16.13.1 or newer, react-native 0.63.2 or newer, and react-native-windows 0.63.3 or newer, with the Windows peer marked optional so that an iOS or Android project does not have to install it. The package itself has no runtime dependencies at all. The dependencies map is empty, which is unusual and worth noting: everything here is native code and a thin JavaScript bridge, so there is no third party JavaScript to keep in step with React Native versions. ## The iOS integration is a manual edit in two files The iOS setup is the part of this module that autolinking does not handle, and it depends on your React Native version. For React Native 0.77 and above, the AppDelegate is Swift, so you add a method to AppDelegate.swift: ```diff + // required for react-native-orientation-locker + func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask { + return Orientation.getOrientation() + } ``` And in the bridging header: ```diff +#import "Orientation.h" ``` For React Native 0.76 and below, the equivalent goes into AppDelegate.m instead. The mechanism is worth understanding. On iOS, the app declares which orientations it supports, and the native module is what tells the system what to return. So the module does not rotate the view itself, it answers the question the operating system asks, and your AppDelegate passes that answer on. That is why the AppDelegate has to be involved, and why the Swift and Objective-C versions need separate instructions, since the method signature differs between them. The bridging header import is needed because the Swift AppDelegate calls into the Objective-C Orientation class. If your project has no bridging header yet, that is the step that creates one. ## The Android side needs a lifecycle callback in MainApplication The Android integration has its own manual step, described in the 1.2.0 change notes as implementing ActivityLifecycleCallbacks on Android. The instruction is to add the registration to the onCreate of your MainApplication: ``` import org.wonday.orientation.OrientationActivityLifecycle; @Override public void onCreate() { ... + registerActivityLifecycleCallbacks(OrientationActivityLifecycle.getInstance()); } ``` The reason is the same shape as the iOS one. Android needs to know the current configuration when an activity is created, and the lifecycle callback is how the module gets that information in time rather than after the first rotation. For manual linking on Android, the package is added to the ReactPackage list in MainApplication.java: ```diff +import org.wonday.orientation.OrientationPackage; + packages.add(new OrientationPackage()); ``` The 1.6.0 release added checks for the broadcast receiver being registered and unregistered, to avoid an IllegalArgumentException, and added the RECEIVER_EXPORTED and RECEIVER_NOT_EXPORTED flags to support Android 14, which is the kind of change that breaks on a platform update if nobody is paying attention. One known issue is called out with a link to issue 55: on React Native 0.58 with Android target SDK 27, a fullscreen activity requesting orientation can raise a java.lang.IllegalStateException saying only fullscreen activities can request orientation. ## The Windows support has hardware conditions Windows support arrived in 1.3.0 as a breaking change, alongside a modified sample project and updated TypeScript definitions, and it comes with two conditions that are easy to miss. The first is that locking to an orientation on Windows only works on devices in tablet mode. The second is that getting information on the device orientation and tracking its changes is only possible on devices with an orientation sensor. If the device running the application does not have the appropriate hardware, getDeviceOrientation() returns UNKNOWN. That is a hardware requirement, not a software one, and it means the module's cross-platform claim has a qualifier on the least common of the three platforms. A Windows desktop app without a sensor can lock the UI orientation in tablet mode but cannot report how the device is being held. The README also documents a nine-step procedure for running the example on a Windows tablet, which is a good indication of how manual the platform is. You open example/windows/example.sln in Visual Studio, use Project, then Publish, then Create App Packages, and the certificate password is password. You select Sideloading, accept the current certificate, choose an output location, copy the example__Test directory to the tablet, install the APPXBUNDLE file with the tablet in developer mode, and then turn on tablet mode to see the locking functionality. The steps end with the reminder that the app should launch once the install completes. ## Where react-native-orientation-locker is the wrong choice The first limitation is that React Native ships orientation APIs of its own, and many of the things this module does are thin wrappers over them. If all you need is to read the current orientation, the platform API and a Dimensions listener will do it without a native dependency, a manual AppDelegate edit and a bridging header. The module earns its keep when you need to lock the orientation, which is a platform-level declaration rather than a value you can read. The second is the integration cost, which is real and ongoing. The iOS path requires code in your AppDelegate and a bridging header, and both of those files change shape between React Native versions, as the split between 0.76 and 0.77 in the documentation shows. Every React Native upgrade is a chance for this module's instructions to be stale, and the maintainer is one person. The third is the maintenance posture, and the numbers here deserve attention. The last tagged release is v1.7.0 from 2024-04-20, with v1.4.0 in November 2021 and v1.3.0 in May 2021 before it, while the last push to the repository was on 2026-05-23. So there has been work on the repository well after the last release tag, and the difference between those two dates is exactly the window in which platform changes accumulate. The peer dependency floor of react-native 0.63.2 tells you the module targets a reasonably modern React Native, but the release cadence has slowed to roughly one tag every year and a half. The comparison with the alternatives is straightforward. If you need orientation locking in a single screen, a small amount of platform code in your own project is often less trouble than a dependency with three platform implementations. If you need it across a suite of apps, or you want the device orientation listener that distinguishes physical rotation from UI rotation, this module has already solved the awkward parts, and the changelog shows the author fixing real problems like the Android 14 receiver flags and a threading issue on Windows. ## Conclusion react-native-orientation-locker fits a React Native app that has to keep a screen in one orientation, such as a kiosk, a player or a checkout flow, and that needs to react to the physical device being turned. It does not fit an app that only needs the platform's own orientation APIs, and it does not fit a Windows desktop app outside tablet mode. Before adopting it, read the setup steps for your platform, since the iOS integration requires AppDelegate and bridging header changes that autolinking does not do for you, register OrientationActivityLifecycle in your Android MainApplication, and check the release history, because the last tagged version is v1.7.0 from April 2024 while the repository was pushed to in May 2026. ## FAQ ### What does react-native-orientation-locker do? It is a React Native module that can lock the screen orientation to PORTRAIT, LANDSCAPE-LEFT, PORTRAIT-UPSIDEDOWN or LANDSCAPE-RIGHT, listen for orientation changes of the device, and report the current orientation, with support for iOS, Android and Windows. ### How do I install react-native-orientation-locker? On React Native 0.60 and above, run `yarn add react-native-orientation-locker` and autolinking handles the native side. On 0.59 and below you also run `react-native link react-native-orientation-locker`, and for iOS you run pod install in the ios directory. ### What manual steps does the iOS setup need? On React Native 0.77 and above you add an application delegate method to AppDelegate.swift that returns Orientation.getOrientation(), and import Orientation.h in the bridging header. On React Native 0.76 and below the equivalent goes into AppDelegate.m instead. ### What does react-native-orientation-locker need on Android? The 1.2.0 release added ActivityLifecycleCallbacks support, and the README asks you to register OrientationActivityLifecycle.getInstance() in the onCreate of your MainApplication. Manual linking adds OrientationPackage to the ReactPackage list in MainApplication.java. ### What are the limits of the Windows support? Locking to an orientation on Windows only works on devices in tablet mode, and getting device orientation information and tracking its changes requires a device with an orientation sensor. Without that hardware, getDeviceOrientation() returns UNKNOWN. ## Sources - [Issues](https://github.com/wonday/react-native-orientation-locker/issues) - [License: MIT](https://github.com/wonday/react-native-orientation-locker/blob/master/LICENSE) - [README](https://github.com/wonday/react-native-orientation-locker/blob/master/README.md) - [Releases](https://github.com/wonday/react-native-orientation-locker/releases) - [wonday/react-native-orientation-locker on GitHub](https://github.com/wonday/react-native-orientation-locker) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wonday-react-native-orientation-locker