{"id":27270283,"url":"https://github.com/gladiuscode/react-native-orientation-director","last_synced_at":"2025-04-11T12:29:52.503Z","repository":{"id":241160009,"uuid":"803523914","full_name":"gladiuscode/react-native-orientation-director","owner":"gladiuscode","description":"A React Native library that allows you to detect device orientation changes, interface orientation changes and lock interface orientation.","archived":false,"fork":false,"pushed_at":"2025-04-10T18:25:36.000Z","size":3409,"stargazers_count":53,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T18:59:11.074Z","etag":null,"topics":["device","handler","interface","listener","orientation","react-native"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gladiuscode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-20T22:20:03.000Z","updated_at":"2025-04-10T18:25:39.000Z","dependencies_parsed_at":"2024-05-22T20:42:16.241Z","dependency_job_id":"833b53ed-1d13-4410-98fd-7100ca95af0b","html_url":"https://github.com/gladiuscode/react-native-orientation-director","commit_stats":null,"previous_names":["gladiuscode/react-native-orientation-handler","gladiuscode/react-native-orientation-director"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gladiuscode%2Freact-native-orientation-director","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gladiuscode%2Freact-native-orientation-director/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gladiuscode%2Freact-native-orientation-director/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gladiuscode%2Freact-native-orientation-director/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gladiuscode","download_url":"https://codeload.github.com/gladiuscode/react-native-orientation-director/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281027,"owners_count":21077417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["device","handler","interface","listener","orientation","react-native"],"created_at":"2025-04-11T12:29:51.977Z","updated_at":"2025-04-11T12:29:52.490Z","avatar_url":"https://github.com/gladiuscode.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![NPM Version](https://img.shields.io/npm/v/react-native-orientation-director)\n\n---\n\n# react-native-orientation-director\n\nA React Native library that allows you to listen to orientation changes, lock interface orientation\nto a selected one and get current orientation.\nWritten in Kotlin, Swift and Typescript. It supports both the Old and New React Native architecture.\n\nThis library takes inspiration from and builds upon the following amazing alternatives:\n\n1. [react-native-orientation-locker](https://github.com/wonday/react-native-orientation-locker)\n2. [react-native-orientation-handler](https://github.com/KroosX4V/react-native-orientation-manager)\n\n## Features\n\n- [x] Get the current orientation of the device\n- [x] Get the current orientation of the interface\n- [x] Get the current interface orientation status (locked or unlocked)\n- [x] Listen to device orientation changes\n- [x] Listen to interface orientation changes\n- [x] Listen to interface orientation status changes\n- [x] Lock the interface orientation to a specific orientation\n- [x] Unlock the interface orientation\n- [x] Reset supported interface orientations to settings\n- [x] Check if autorotation is enabled (Android only)\n\n## Installation\n\n### React Native Bare\n\nYou can install the package via npm or yarn:\n\n```sh\nnpm install react-native-orientation-director\n```\n\n```sh\nyarn add react-native-orientation-director\n```\n\nDon't forget to run pod-install.\n\n### Expo\n\nYou can install the package like any other Expo package, using the following command:\n\n```sh\nnpx expo install react-native-orientation-director\n```\n\n## Setup\n\n### Expo\n\nSimply add the library plugin to your `app.json` file:\n\n```json\n{\n  \"expo\": {\n    \"plugins\": [\n      \"react-native-orientation-director\"\n    ]\n  }\n}\n```\n\nThis way, Expo will handle the native setup for you during `prebuild`.\n\n\u003e Note: only SDK 50 and above are supported, the plugin is configured to handle only the kotlin template.\n\n### Bare\n\n#### Android\n\nThis library uses a custom broadcast receiver to handle the manual orientation changes: when the user disables the\nautorotation feature and the system prompts the user to rotate the device, the library will listen to the broadcast\nsent by the MainActivity and update the interface orientation accordingly.\n\nTo allow the library to listen to the broadcast, you need to override the `onConfigurationChanged` method in your\nMainActivity file, as shown below:\n\n```kotlin\noverride fun onConfigurationChanged(newConfig: Configuration) {\n    super.onConfigurationChanged(newConfig)\n\n    val orientationDirectorCustomAction =\n      \"${packageName}.${ConfigurationChangedBroadcastReceiver.CUSTOM_INTENT_ACTION}\"\n\n    val intent =\n      Intent(orientationDirectorCustomAction).apply {\n        putExtra(\"newConfig\", newConfig)\n        setPackage(packageName)\n      }\n\n    this.sendBroadcast(intent)\n}\n```\n\nNothing else is required for Android.\n\n#### iOS\n\nTo properly handle interface orientation changes in iOS, you need to update your AppDelegate file. Since React Native\n0.77, the AppDelegate has been migrated to Swift, so see the instructions below for both Swift and Objective-C.\n\n##### Objective-C\n\nIn your AppDelegate.h file, import \"OrientationDirector.h\" and implement supportedInterfaceOrientationsForWindow method as follows:\n\n```objc\n#import \u003cOrientationDirector.h\u003e\n\n- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window\n{\n  return [OrientationDirector getSupportedInterfaceOrientationsForWindow];\n}\n```\n\n##### Swift\n\nYou need to create a [bridging header](https://developer.apple.com/documentation/swift/importing-objective-c-into-swift#Import-Code-Within-an-App-Target)\nto import the library, as shown below:\n\n```\n#import \"OrientationDirector.h\"\n```\n\nThen, in your AppDelegate.swift file, implement the supportedInterfaceOrientationsFor method as follows:\n\n```swift\noverride func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -\u003e UIInterfaceOrientationMask {\n  return OrientationDirector.getSupportedInterfaceOrientationsForWindow()\n}\n```\n\nIf you need help, you can check the example project.\n\n## Usage\n\nThis library exports a class called: [RNOrientationDirector](https://github.com/gladiuscode/react-native-orientation-director/blob/main/src/RNOrientationDirector.ts) that exposes the following methods:\n\n| Method                                   | Description                                                                       |\n|------------------------------------------|-----------------------------------------------------------------------------------|\n| getInterfaceOrientation                  | Returns the last interface orientation                                            |\n| getDeviceOrientation                     | Returns the last device orientation                                               |\n| lockTo                                   | Locks the interface to a specific orientation                                     |\n| unlock                                   | Unlock the interface                                                              |\n| isLocked                                 | Returns the current interface orientation status (locked / unlocked)              |\n| isAutoRotationEnabled                    | (Android Only) Returns if auto rotation is enabled                                |\n| listenForDeviceOrientationChanges        | Triggers a provided callback each time the device orientation changes             |\n| listenForInterfaceOrientationChanges     | Triggers a provided callback each time the interface orientation changes          |\n| listenForLockChanges                     | Triggers a provided callback each time the interface orientation status changes   |\n| convertOrientationToHumanReadableString  | Returns a human readable string based on the given orientation                    |\n| convertAutoRotationToHumanReadableString | Returns a human readable string based on the given auto rotation                  |\n| setHumanReadableOrientations             | Sets the mapping needed to convert orientation values to human readable strings   |\n| setHumanReadableAutoRotations            | Sets the mapping needed to convert auto rotation values to human readable strings |\n| resetSupportedInterfaceOrientations      | Resets the supported interface orientations to settings                           |\n| isLockableOrientation                    | Determines if orientation is lockable                                             |\n\nIn addition, the library exposes the following hooks:\n\n| Hook                                                                                                                                                            | Description                                                             |\n|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|\n| [useInterfaceOrientation](https://github.com/gladiuscode/react-native-orientation-director/blob/main/src/hooks/useInterfaceOrientation.hook.ts)                 | Returns the current interface orientation and listens to changes        |\n| [useDeviceOrientation](https://github.com/gladiuscode/react-native-orientation-director/blob/main/src/hooks/useDeviceOrientation.hook.ts)                       | Returns the current device orientation and listens to changes           |\n| [useIsInterfaceOrientationLocked](https://github.com/gladiuscode/react-native-orientation-director/blob/main/src/hooks/useIsInterfaceOrientationLocked.hook.ts) | Returns the current interface orientation status and listens to changes |\n\nHead over to the [example project](example) to see how to use the library.\n\n### Warning\n\nPlease be aware that there is a subtle difference between the device orientation\nand the interface orientation.\n\nWhen you device is either in landscape left or right orientation, your interface\nis inverted, this is why lockTo method needs a second parameter to discriminate\nwhich type of orientation your are supplying.\n\nTo match developers expectations, if you supply a device orientation and\nOrientationType.device, lockTo switches landscapeRight with left and vice versa\nto property align the interface orientation.\n\nThis behavior comes from the native API, you can find more information in their\ndocumentation:\n\n1. [iOS - UIInterfaceOrientation](https://developer.apple.com/documentation/uikit/uiinterfaceorientation)\n2. [iOS - UIDeviceOrientation](https://developer.apple.com/documentation/uikit/uideviceorientation)\n3. [Android - getRotation](\u003chttps://developer.android.com/reference/android/view/Display#getRotation()\u003e)\n\n### Android\n\nSince on Android we need to deal with sensors and their usage, it is worth noting that the device orientation computation works\ndifferently than on iOS, mainly in the following ways:\n\n1. Upon start up, all required sensors are enabled just for the initial device orientation computation, then they are disabled;\n2. Each time a new device orientation listener is added, all required sensors are enabled if disabled;\n3. After the last device orientation listener is removed, all required sensors are disabled;\n\nThis behavior allows us to follow Google's best practices related to the Sensors Framework. More [here](https://developer.android.com/develop/sensors-and-location/sensors/sensors_overview#sensors-practices).\n\n## Roadmap\n\n- [ ] Add JS side tests\n- [ ] Add iOS side tests\n\n## Contributing\n\nSee the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.\n\n---\n\nMade with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgladiuscode%2Freact-native-orientation-director","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgladiuscode%2Freact-native-orientation-director","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgladiuscode%2Freact-native-orientation-director/lists"}