whitestranger7
react-native-orientation-turbo 🚀
A React Native library for controlling device orientation with support for locking to portrait, landscape orientations, and real-time orientation change subscriptions. Built with Turbo Modules for optimal performance.
Features
- Modern Architecture: Built with React Native Turbo Modules
- Cross Platform: Support for both iOS and Android
- Orientation Locking: Lock to portrait or landscape orientations
- Early Orientation Locking: Lock orientation before React Native loads (before bootsplash)
- AndroidManifest.xml Sync: Automatic synchronization with Android manifest orientation settings
- State Synchronization: Seamless state sync between Native and JavaScript contexts
- Event Subscriptions: Subscribe to orientation changes with live updates
- TypeScript: Full TypeScript support with type definitions
- Performance: Native performance with Turbo Module architecture
Requirements
- React Native 0.76+ (Turbo Modules support required)
- iOS 15.1+
- Android API level 24+ (Android 7.0)
- New Architecture enabled (Turbo Modules)
Important: This library requires the New Architecture (Turbo Modules) to be enabled. It does not support the legacy bridge.
Installation
npm install react-native-orientation-turboor
yarn add react-native-orientation-turboiOS Setup
Install pods:
cd ios && pod installModify your
AppDelegate.swiftfile:
Add the import statement:
import OrientationTurboAdd the orientation support method:
func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
return OrientationTurbo.shared.getSupportedInterfaceOrientations()
}Your AppDelegate.swift should look like this:
import UIKit
import React
import React_RCTAppDelegate
import ReactAppDependencyProvider
import OrientationTurbo // Add this import
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
// ... other code ...
// Add this method
func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
return OrientationTurbo.shared.getSupportedInterfaceOrientations()
}
}Android Setup
No additional setup required for Android.
Note: The library automatically syncs with your
AndroidManifest.xmlorientation settings. If you haveandroid:screenOrientationset in your manifest, the library will respect and sync with those settings into state on initialization.
Migration Guide
If you're upgrading from a previous version, please check our Migration Guide for any breaking changes and upgrade instructions.
v2.2.0 Breaking Changes: iOS native API changed from OrientationTurboImpl.shared to OrientationTurbo.shared. React Native usage remains unchanged.
Usage
import {
lockToPortrait,
lockToLandscape,
unlockAllOrientations,
getCurrentOrientation,
isLocked,
getDeviceAutoRotateStatus,
onOrientationChange,
onLockOrientationChange,
startOrientationTracking,
stopOrientationTracking,
PortraitDirection,
Orientation,
LandscapeDirection,
type OrientationSubscription,
type LockOrientationSubscription,
type DeviceAutoRotateStatus,
} from 'react-native-orientation-turbo';Basic Examples
// Starts tracking native sensors for onOrientationChange.
startOrientationTracking();
// Stops tracking native sensors.
stopOrientationTracking();
// Lock to portrait orientation
lockToPortrait();
// Lock to portrait UPSIDE_DOWN orientation
lockToPortrait(PortraitDirection.UPSIDE_DOWN);
// Lock to landscape left
lockToLandscape(LandscapeDirection.LEFT);
// Lock to landscape right
lockToLandscape(LandscapeDirection.RIGHT);
// Unlock all orientations (allow rotation)
unlockAllOrientations();
// Get current orientation. If screen is locked - returns lock state, if not - returns current device orientation
const currentOrientation = getCurrentOrientation();
console.log(currentOrientation); // 'PORTRAIT' | 'LANDSCAPE_LEFT' | 'LANDSCAPE_RIGHT' | 'FACE_UP' | 'FACE_DOWN'
// Check if orientation is currently locked
const locked = isLocked();
console.log(locked); // true | false
// Get device auto-rotate status (Android only). iOS will return null
const autoRotateStatus = getDeviceAutoRotateStatus();
console.log(autoRotateStatus); // { isAutoRotateEnabled: boolean, canDetectOrientation: boolean } | null
// Subscribe to lock orientation changes
onLockOrientationChange(({ orientation, isLocked }) => {
// Your code there
})
// Subscribe to device orientation changes
onOrientationChange(({ orientation }) => {
// Your code there
})API Reference
Methods
startOrientationTracking(): void
Starts using native sensors to track device orientation changes.
When device is physically rotates - sensors are detecting changes and expose it via onOrientationChange subscription.
Drains battery faster and uses device power resources.
Recommended to use only when sensors are needed and remove when not needed remove sensors tracking by using stopOrientationTracking.
startOrientationTracking();stopOrientationTracking(): void
Stops using native sensors if it's used. Physical devices rotation would no longer be tracked.
stopOrientationTracking();lockToPortrait(direction?: PortraitDirection): void
Locks the device orientation to portrait mode.
Parameters:
direction?:PortraitDirection.UPorPortraitDirection.UPSIDE_DOWNorundefined
import { PortraitDirection } from 'react-native-orientation-turbo';
lockToPortrait(); // same as lockToPortrait(PortraitDirection.UP)
lockToPortrait(PortraitDirection.UP);
lockToPortrait(PortraitDirection.UPSIDE_DOWN);lockToLandscape(direction: LandscapeDirection): void
Locks the device orientation to landscape mode in the specified direction.
Parameters:
direction:LandscapeDirection.LEFTorLandscapeDirection.RIGHT
import { LandscapeDirection } from 'react-native-orientation-turbo';
lockToLandscape(LandscapeDirection.LEFT);
lockToLandscape(LandscapeDirection.RIGHT);unlockAllOrientations(): void
Unlocks the orientation, allowing the device to rotate freely based on device rotation.
unlockAllOrientations();getCurrentOrientation(): string
Returns the current device orientation.
Returns: 'PORTRAIT' | 'LANDSCAPE_LEFT' | 'LANDSCAPE_RIGHT' | 'FACE_UP' | 'FACE_DOWN'
const orientation = getCurrentOrientation();isLocked(): boolean
Returns whether the orientation is currently locked.
Returns: true if orientation is locked, false if unlocked
const locked = isLocked();getDeviceAutoRotateStatus(): DeviceAutoRotateStatus | null
Android only. Returns information about the device's auto-rotate settings and orientation detection capabilities.
Returns:
DeviceAutoRotateStatusobject on Androidnullon iOS (not supported)
iOS Limitation: This method is not available on iOS due to platform restrictions. See iOS Auto-Rotate Detection Limitations for detailed explanation and alternative approaches.
DeviceAutoRotateStatus Properties:
isAutoRotateEnabled:boolean- Whether auto-rotate is enabled in device settingscanDetectOrientation:boolean- Whether the device can detect orientation changes
import { getDeviceAutoRotateStatus } from 'react-native-orientation-turbo';
const status = getDeviceAutoRotateStatus();
if (status) {
console.log('Auto-rotate enabled:', status.isAutoRotateEnabled);
console.log('Can detect orientation:', status.canDetectOrientation);
} else {
console.log('Auto-rotate status not supported on this platform');
}Subscriptions
onLockOrientationChange(callback: (subscription: LockOrientationSubscription) => void)
Subscribes to orientation changes and receives real-time updates.
Parameters:
callback: Function called when lock state orientation changes, receivesLockOrientationSubscriptionobject
Returns: Subscription object with remove() method to unsubscribe
import { onLockOrientationChange } from 'react-native-orientation-turbo';
const subscription = onLockOrientationChange(({ orientation, isLocked }) => {
console.log('Current orientation:', orientation);
console.log('Is locked:', isLocked);
});
// Unsubscribe when no longer needed
subscription.remove();React Hook Example:
import { useEffect, useRef } from 'react';
import type { EventSubscription } from 'react-native';
import { onLockOrientationChange } from 'react-native-orientation-turbo';
const MyComponent = () => {
const lockListenerSubscription = useRef<null | EventSubscription>(null);
useEffect(() => {
lockListenerSubscription.current = onLockOrientationChange(({ orientation, isLocked }) => {
// Handle orientation change
console.log('Orientation:', orientation, 'Locked:', isLocked);
});
return () => {
lockListenerSubscription.current?.remove();
lockListenerSubscription.current = null;
}; // Clean up subscription
}, []);
return <View>{/* Your component */}</View>;
};onOrientationChange(callback: (subscription: OrientationSubscription) => void)
Subscribes to orientation changes and receives real-time updates.
Parameters:
callback: Function called when device physical orientation changes, receivesOrientationSubscriptionobject
Returns: Subscription object with remove() method to unsubscribe
import { onOrientationChange } from 'react-native-orientation-turbo';
const subscription = onOrientationChange(({ orientation }) => {
console.log('Current device orientation:', orientation);
});
// Unsubscribe when no longer needed
subscription.remove();React Hook Example:
import { useEffect, useRef } from 'react';
import type { EventSubscription } from 'react-native';
import { onOrientationChange } from 'react-native-orientation-turbo';
const MyComponent = () => {
const listenerSubscription = useRef<null | EventSubscription>(null);
useEffect(() => {
listenerSubscription.current = onOrientationChange(({ orientation }) => {
// Handle orientation change
console.log('Orientation:', orientation);
});
return () => {
listenerSubscription.current?.remove();
listenerSubscription.current = null;
}; // Clean up subscription
}, []);
return <View>{/* Your component */}</View>;
};Types
LandscapeDirection
enum LandscapeDirection {
LEFT = 'LEFT',
RIGHT = 'RIGHT',
}PortraitDirection
enum PortraitDirection {
UP = 'UP',
UPSIDE_DOWN = 'UPSIDE_DOWN', // iOS only
}Orientation
enum Orientation {
PORTRAIT = 'PORTRAIT',
LANDSCAPE_LEFT = 'LANDSCAPE_LEFT',
LANDSCAPE_RIGHT = 'LANDSCAPE_RIGHT',
FACE_UP = 'FACE_UP', // iOS only
FACE_DOWN = 'FACE_DOWN', // iOS only
}LockOrientationSubscription
type LockOrientationSubscription = {
orientation: Orientation | null;
isLocked: boolean;
};OrientationSubscription
type OrientationSubscription = {
orientation: Orientation;
};DeviceAutoRotateStatus
type DeviceAutoRotateStatus = {
isAutoRotateEnabled: boolean;
canDetectOrientation: boolean;
};Advanced Features
Early Orientation Locking
Lock orientation before React Native loads (useful for preventing orientation changes during app initialization/bootsplash):
iOS - AppDelegate.swift:
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
// Lock orientation BEFORE React Native loads
OrientationTurbo.shared.lockToPortrait()
// Your existing setup...
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}Android - MainActivity.kt:
override fun onCreate(savedInstanceState: Bundle?) {
// Lock orientation BEFORE React Native loads
OrientationTurbo.lockToPortrait(this)
super.onCreate(savedInstanceState)
}AndroidManifest.xml Synchronization
The library automatically syncs with your Android manifest orientation settings:
<activity android:screenOrientation="portrait">
<!-- Library will automatically sync to portrait on initialization -->
</activity>State Synchronization
Early orientation locks are automatically synchronized with your JavaScript context when the library initializes, ensuring consistent state across native and JavaScript.
For comprehensive documentation on advanced features, early orientation locking, state synchronization, and integration patterns, see Advanced Usage Guide.
For detailed information on using the library natively in iOS and Android applications, including architecture, restrictions, and best practices, see Native Usage Guide.
Complete Example
Please visit example folder on github page.
Enabling New Architecture
This library requires React Native's New Architecture (Turbo Modules). Please refer to React Native docs on how to enable it.
Contributing
See the contributing guide to learn how to contribute to the repository and the development workflow.
License
MIT
Made with create-react-native-library