react-native-orientation-kit

A React Native library for real-time device orientation detection with detailed orientation types and event listeners.

Installation

npm install react-native-orientation-kit

For Manual Orientation Control Features

The manual orientation control features (setOrientation, lockOrientation, etc.) require native code changes. After installation, you need to rebuild your project:

React Native CLI:

# Android
cd android && ./gradlew clean && cd .. && npx react-native run-android

# iOS
cd ios && rm -rf build && cd .. && npx react-native run-ios

Expo:

expo run:android  # or expo run:ios

See SETUP.md for detailed setup instructions.

Usage

Basic Usage

import { getCurrentOrientation } from 'react-native-orientation-kit';

// Get current device orientation
const orientation = getCurrentOrientation();
console.log(orientation); // "portrait", "landscape-left", etc.

Real-time Orientation Listening (Keyboard-like API)

import { Orientation } from 'react-native-orientation-kit';

// Add event listener for orientation changes (similar to Keyboard.addListener)
const subscription = Orientation.addListener(
  'orientationDidChange',
  (event) => {
    console.log('Orientation changed to:', event.orientation);
  }
);

// Clean up when done
subscription.remove();

// Or remove all listeners
Orientation.removeAllListeners('orientationDidChange');

Manual Orientation Control

import {
  setOrientation,
  lockOrientation,
  unlockOrientation,
  isOrientationLocked,
} from 'react-native-orientation-kit';

// Set device to specific orientation
setOrientation('portrait');
setOrientation('landscape-left');
setOrientation('auto'); // Enable auto-rotation

// Lock orientation to current orientation
lockOrientation('current');

// Lock to specific orientation
lockOrientation('portrait');
lockOrientation('landscape-left');

// Unlock orientation (allow auto-rotation)
unlockOrientation();

// Check if orientation is locked
const locked = isOrientationLocked();
console.log('Orientation locked:', locked);

Using the Orientation Object

import { Orientation } from 'react-native-orientation-kit';

// All methods are also available on the Orientation object
Orientation.setOrientation('portrait');
Orientation.lockOrientation('current');
Orientation.unlockOrientation();
const locked = Orientation.isOrientationLocked();

Legacy API (still supported)

import {
  addOrientationListener,
  removeOrientationListener,
  startOrientationListener,
  stopOrientationListener,
} from 'react-native-orientation-kit';

// Start the orientation listener
startOrientationListener();

// Add event listener for orientation changes
const subscription = addOrientationListener((event) => {
  console.log('Orientation changed to:', event.orientation);
});

// Clean up when done
removeOrientationListener(subscription);
stopOrientationListener();

React Hook Example (Recommended)

import React, { useState, useEffect } from 'react';
import {
  getCurrentOrientation,
  Orientation,
} from 'react-native-orientation-kit';

function useOrientation() {
  const [orientation, setOrientation] = useState(getCurrentOrientation());

  useEffect(() => {
    // Using the new Keyboard-like API
    const subscription = Orientation.addListener(
      'orientationDidChange',
      (event) => {
        setOrientation(event.orientation);
      }
    );

    return () => {
      subscription.remove(); // Automatically handles native listener cleanup
    };
  }, []);

  return orientation;
}

export default function App() {
  const orientation = useOrientation();

  return (
    <View>
      <Text>Current orientation: {orientation}</Text>
    </View>
  );
}

Supported Orientations

This library supports all device orientations available on both iOS and Android:

Standard Orientations

• Portrait - Normal upright position
• Portrait Upside Down - Rotated 180° from portrait
• Landscape Left - Rotated 90° counter-clockwise from portrait
• Landscape Right - Rotated 90° clockwise from portrait

Flat Orientations

• Face Up - Device lying flat with screen facing up
• Face Down - Device lying flat with screen facing down

Platform Mapping

iOS (UIDeviceOrientation)

• UIDeviceOrientationPortrait → "portrait"
• UIDeviceOrientationPortraitUpsideDown → "portrait-upside-down"
• UIDeviceOrientationLandscapeLeft → "landscape-left"
• UIDeviceOrientationLandscapeRight → "landscape-right"
• UIDeviceOrientationFaceUp → "face-up"
• UIDeviceOrientationFaceDown → "face-down"

Android (Surface Rotation + Accelerometer)

• ROTATION_0 → "portrait"
• ROTATION_180 → "portrait-upside-down"
• ROTATION_90 → "landscape-left"
• ROTATION_270 → "landscape-right"
• Accelerometer Z-axis > 0.8g → "face-up"
• Accelerometer Z-axis < -0.8g → "face-down"

API Reference

Types

type OrientationType =
  | 'portrait'
  | 'portrait-upside-down'
  | 'landscape-left'
  | 'landscape-right'
  | 'face-up'
  | 'face-down'
  | 'unknown';

interface OrientationChangeEvent {
  orientation: OrientationType;
}

Methods

getCurrentOrientation(): OrientationType

Returns the current device orientation:

• "portrait" - Device is in normal portrait mode
• "portrait-upside-down" - Device is upside down
• "landscape-left" - Device rotated 90° counter-clockwise
• "landscape-right" - Device rotated 90° clockwise
• "face-up" - Device is lying flat with screen facing up
• "face-down" - Device is lying flat with screen facing down
• "unknown" - Orientation could not be determined

startOrientationListener(): void

Starts the native orientation listener. Must be called before adding event listeners.

stopOrientationListener(): void

Stops the native orientation listener and cleans up resources.

Orientation.addListener(eventType, callback)

Adds a listener for orientation change events (similar to Keyboard.addListener).

Parameters:

• eventType - Currently only supports 'orientationDidChange'
• callback - Function called when orientation changes

Returns: EmitterSubscription object with a remove() method

Example:

const subscription = Orientation.addListener(
  'orientationDidChange',
  (event) => {
    console.log('New orientation:', event.orientation);
  }
);

// Later, remove the listener
subscription.remove();

Orientation.removeAllListeners(eventType)

Removes all orientation listeners for the specified event type.

Parameters:

• eventType - Currently only supports 'orientationDidChange'

Legacy Methods (still supported)

addOrientationListener(callback: (event: OrientationChangeEvent) => void)

Adds a listener for orientation change events. Returns a subscription object.

removeOrientationListener(subscription: EmitterSubscription): void

Removes a specific orientation listener.

removeAllOrientationListeners(): void

Removes all orientation listeners.

Manual Orientation Control Methods

setOrientation(orientation: OrientationType | 'auto'): void

Sets the device orientation to a specific orientation or enables auto-rotation.

Parameters:

• orientation - Target orientation: 'portrait', 'landscape-left', 'landscape-right', 'portrait-upside-down', or 'auto'

lockOrientation(orientation: OrientationType | 'current'): void

Locks the device orientation to prevent auto-rotation.

Parameters:

• orientation - Orientation to lock to, or 'current' to lock to the current orientation

unlockOrientation(): void

Unlocks the device orientation, allowing auto-rotation based on device sensors.

isOrientationLocked(): boolean

Returns whether the orientation is currently locked.

Returns: true if orientation is locked, false otherwise

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library