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-turbo

or

yarn add react-native-orientation-turbo

iOS Setup

1. Install pods:

cd ios && pod install

2. Modify your AppDelegate.swift file:

Add the import statement:

import OrientationTurbo

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

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.UP or PortraitDirection.UPSIDE_DOWN or undefined

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

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:

• 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

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, receives LockOrientationSubscription object

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, receives OrientationSubscription object

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