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

``sh
npm install react-native-orientation-turbo
`

or

`sh
yarn add react-native-orientation-turbo
`

$3

1. Install pods:
`sh
cd ios && pod install
`

2. Modify your AppDelegate.swift file:

Add the import statement:
`swift
import OrientationTurbo
`

Add the orientation support method:
`swift
func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
return OrientationTurbo.shared.getSupportedInterfaceOrientations()
}
`

Your AppDelegate.swift should look like this:
`swift
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()
}
}
`

$3

No additional setup required for Android.

> Note: The library automatically syncs with your AndroidManifest.xml orientation settings. If you have android:screenOrientation set 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

`typescript
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';
`

$3

`typescript
// 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

$3

#### 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.

`typescript
startOrientationTracking();
`

#### stopOrientationTracking(): void

Stops using native sensors if it's used. Physical devices rotation would no longer be tracked.

`typescript
stopOrientationTracking();
`

#### lockToPortrait(direction?: PortraitDirection): void

Locks the device orientation to portrait mode.

Parameters:
- direction?: PortraitDirection.UP or PortraitDirection.UPSIDE_DOWN or undefined

`typescript
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.LEFT or LandscapeDirection.RIGHT

`typescript
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.

`typescript
unlockAllOrientations();
`

#### getCurrentOrientation(): string

Returns the current device orientation.

Returns: 'PORTRAIT' | 'LANDSCAPE_LEFT' | 'LANDSCAPE_RIGHT' | 'FACE_UP' | 'FACE_DOWN'

`typescript
const orientation = getCurrentOrientation();
`

#### isLocked(): boolean

Returns whether the orientation is currently locked.

Returns: true if orientation is locked, false if unlocked

`typescript
const locked = isLocked();
`

#### getDeviceAutoRotateStatus(): DeviceAutoRotateStatus | null

Android only. Returns information about the device's auto-rotate settings and orientation detection capabilities.

Returns:
- DeviceAutoRotateStatus object on Android
- null on 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 settings
- canDetectOrientation: boolean - Whether the device can detect orientation changes

`typescript
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');
}
`

$3

#### onLockOrientationChange(callback: (subscription: LockOrientationSubscription) => void)

Subscribes to orientation changes and receives real-time updates.

Parameters:
- callback: Function called when lock state orientation changes, receives LockOrientationSubscription object

Returns: Subscription object with remove() method to unsubscribe

`typescript
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:
`typescript
import { useEffect, useRef } from 'react';
import type { EventSubscription } from 'react-native';

import { onLockOrientationChange } from 'react-native-orientation-turbo';

const MyComponent = () => {
const lockListenerSubscription = useRef(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 {/ Your component /};
};
`

#### onOrientationChange(callback: (subscription: OrientationSubscription) => void)

Subscribes to orientation changes and receives real-time updates.

Parameters:
- callback: Function called when device physical orientation changes, receives OrientationSubscription object

Returns: Subscription object with remove() method to unsubscribe

`typescript
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:
`typescript
import { useEffect, useRef } from 'react';
import type { EventSubscription } from 'react-native';

import { onOrientationChange } from 'react-native-orientation-turbo';

const MyComponent = () => {
const listenerSubscription = useRef(null);

useEffect(() => {
listenerSubscription.current = onOrientationChange(({ orientation }) => {
// Handle orientation change
console.log('Orientation:', orientation);
});

return () => {
listenerSubscription.current?.remove();
listenerSubscription.current = null;
}; // Clean up subscription
}, []);

return {/ Your component /};
};
`

$3

#### LandscapeDirection

`typescript
enum LandscapeDirection {
LEFT = 'LEFT',
RIGHT = 'RIGHT',
}
`

#### PortraitDirection

`typescript
enum PortraitDirection {
UP = 'UP',
UPSIDE_DOWN = 'UPSIDE_DOWN', // iOS only
}
`

#### Orientation

`typescript
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

`typescript
type LockOrientationSubscription = {
orientation: Orientation | null;
isLocked: boolean;
};
`

#### OrientationSubscription

`typescript
type OrientationSubscription = {
orientation: Orientation;
};
`

#### DeviceAutoRotateStatus

`typescript
type DeviceAutoRotateStatus = {
isAutoRotateEnabled: boolean;
canDetectOrientation: boolean;
};
`

Advanced Features

$3

Lock orientation before React Native loads (useful for preventing orientation changes during app initialization/bootsplash):

iOS - AppDelegate.swift:
`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:
`kotlin
override fun onCreate(savedInstanceState: Bundle?) {
// Lock orientation BEFORE React Native loads
OrientationTurbo.lockToPortrait(this)

super.onCreate(savedInstanceState)
}
`

$3

The library automatically syncs with your Android manifest orientation settings:

`xml



`

$3

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