npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

react-native-orientation-director

v2.1.0

Published

A Modern React Native library that allows you to access orientation

Downloads

294

Readme

NPM Version


react-native-orientation-director

A React Native library that allows you to listen to orientation changes, lock interface orientation to a selected one and get current orientation. Written in Kotlin, Swift and Typescript. It supports both the Old and New React Native architecture.

This library takes inspiration from and builds upon the following amazing alternatives:

  1. react-native-orientation-locker
  2. react-native-orientation-handler

Features

  • [x] Get the current orientation of the device
  • [x] Get the current orientation of the interface
  • [x] Get the current interface orientation status (locked or unlocked)
  • [x] Listen to device orientation changes
  • [x] Listen to interface orientation changes
  • [x] Listen to interface orientation status changes
  • [x] Lock the interface orientation to a specific orientation
  • [x] Unlock the interface orientation
  • [x] Reset supported interface orientations to settings
  • [x] Check if autorotation is enabled (Android only)

Installation

React Native Bare

You can install the package via npm or yarn:

npm install react-native-orientation-director
yarn add react-native-orientation-director

Don't forget to run pod-install.

Expo

This library can be installed only for Development Builds using the following command:

npx expo install react-native-orientation-director

Setup

To properly handle interface orientation changes in iOS, you need to update your AppDelegate.mm file. In your AppDelegate.mm file, import "OrientationDirector.h" and implement supportedInterfaceOrientationsForWindow method as follows:

#import <OrientationDirector.h>

- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window
{
  return [OrientationDirector getSupportedInterfaceOrientationsForWindow];
}

If you need help, you can check the example project.

There is no need to do anything in Android, it works out of the box.

Usage

This library exports a class called: RNOrientationDirector that exposes the following methods:

| Method | Description | | ---------------------------------------- | --------------------------------------------------------------------------------- | | getInterfaceOrientation | Returns the last interface orientation | | getDeviceOrientation | Returns the last device orientation | | lockTo | Locks the interface to a specific orientation | | unlock | Unlock the interface | | isLocked | Returns the current interface orientation status (locked / unlocked) | | isAutoRotationEnabled | (Android Only) Returns if auto rotation is enabled | | listenForDeviceOrientationChanges | Triggers a provided callback each time the device orientation changes | | listenForInterfaceOrientationChanges | Triggers a provided callback each time the interface orientation changes | | listenForLockChanges | Triggers a provided callback each time the interface orientation status changes | | convertOrientationToHumanReadableString | Returns a human readable string based on the given orientation | | convertAutoRotationToHumanReadableString | Returns a human readable string based on the given auto rotation | | setHumanReadableOrientations | Sets the mapping needed to convert orientation values to human readable strings | | setHumanReadableAutoRotations | Sets the mapping needed to convert auto rotation values to human readable strings | | resetSupportedInterfaceOrientations | Resets the supported interface orientations to settings | | isLockableOrientation | Determines if orientation is lockable |

In addition, the library exposes the following hooks:

| Hook | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | useInterfaceOrientation | Returns the current interface orientation and listens to changes | | useDeviceOrientation | Returns the current device orientation and listens to changes | | useIsInterfaceOrientationLocked | Returns the current interface orientation status and listens to changes |

Head over to the example project to see how to use the library.

Warning

Please be aware that there is a subtle difference between the device orientation and the interface orientation.

When you device is either in landscape left or right orientation, your interface is inverted, this is why lockTo method needs a second parameter to discriminate which type of orientation your are supplying.

To match developers expectations, if you supply a device orientation and OrientationType.device, lockTo switches landscapeRight with left and vice versa to property align the interface orientation.

This behavior comes from the native API, you can find more information in their documentation:

  1. iOS - UIInterfaceOrientation
  2. iOS - UIDeviceOrientation
  3. Android - getRotation

Android

Since on Android we need to deal with sensors and their usage, it is worth noting that the device orientation computation works differently than on iOS, mainly in the following ways:

  1. Upon start up, all required sensors are enabled just for the initial device orientation computation, then they are disabled;
  2. Each time a new device orientation listener is added, all required sensors are enabled if disabled;
  3. After the last device orientation listener is removed, all required sensors are disabled;

This behavior allows us to follow Google's best practices related to the Sensors Framework. More here.

Roadmap

  • [ ] Add JS side tests
  • [ ] Add iOS side tests

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.


Made with create-react-native-library