{"id":42102124,"url":"https://github.com/Cap-go/capacitor-screen-orientation","last_synced_at":"2026-02-05T13:00:51.496Z","repository":{"id":326581707,"uuid":"1106076182","full_name":"Cap-go/capacitor-screen-orientation","owner":"Cap-go","description":"Capacitor plugin  for screen orientation with support for detecting true physical device orientation","archived":false,"fork":false,"pushed_at":"2026-01-28T17:41:49.000Z","size":537,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T07:47:58.296Z","etag":null,"topics":["capacitor","capacitor-plugin"],"latest_commit_sha":null,"homepage":"https://capgo.app/?ref=plugin_screen_orientation","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cap-go.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Cap-go","patreon":null,"open_collective":"capgo","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2025-11-28T15:37:04.000Z","updated_at":"2026-01-28T17:46:23.000Z","dependencies_parsed_at":"2026-01-28T19:02:48.628Z","dependency_job_id":null,"html_url":"https://github.com/Cap-go/capacitor-screen-orientation","commit_stats":null,"previous_names":["cap-go/capacitor-screen-orientation"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Cap-go/capacitor-screen-orientation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-screen-orientation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-screen-orientation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-screen-orientation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-screen-orientation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cap-go","download_url":"https://codeload.github.com/Cap-go/capacitor-screen-orientation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-screen-orientation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28963246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T00:42:38.011Z","status":"ssl_error","status_checked_at":"2026-02-01T00:42:35.920Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["capacitor","capacitor-plugin"],"created_at":"2026-01-26T13:00:21.333Z","updated_at":"2026-02-05T13:00:51.489Z","avatar_url":"https://github.com/Cap-go.png","language":"Swift","funding_links":["https://github.com/sponsors/Cap-go","https://opencollective.com/capgo"],"categories":["Capgo Capacitor Plugins","[Capgo plugins](https://capgo.app/)"],"sub_categories":["UI \u0026 Display"],"readme":"# @capgo/capacitor-screen-orientation\n\n \u003ca href=\"https://capgo.app/\"\u003e\u003cimg src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/?ref=plugin_screen_orientation\"\u003e ➡️ Get Instant updates for your App with Capgo\u003c/a\u003e\u003c/h2\u003e\n  \u003ch2\u003e\u003ca href=\"https://capgo.app/consulting/?ref=plugin_screen_orientation\"\u003e Missing a feature? We'll build the plugin for you 💪\u003c/a\u003e\u003c/h2\u003e\n\u003c/div\u003e\n\n\n\nScreen orientation plugin with support for detecting true physical device orientation\n\n## Features\n\n- 📱 Full Screen Orientation API support\n- 🔍 **Detect true physical device orientation** using motion sensors (even when orientation lock is enabled)\n  - iOS: Uses Core Motion framework\n  - Android: Uses accelerometer sensor\n- 🔒 **Detect if orientation lock is enabled** by comparing physical vs UI orientation\n- 🔄 Real-time orientation change detection\n- 🎯 Lock orientation to specific modes\n- 🌐 Web platform support\n\n**Important Note:** This plugin can detect the physical orientation of the device using motion sensors, but it **cannot bypass the UI orientation lock**. The screen will still respect the user's orientation lock setting. This is useful for knowing how the device is physically held vs. how the UI is displayed.\n\n## Documentation\n\nThe most complete doc is available here: https://capgo.app/docs/plugins/screen-orientation/\n\n## Compatibility\n\n| Plugin version | Capacitor compatibility | Maintained |\n| -------------- | ----------------------- | ---------- |\n| v8.\\*.\\*       | v8.\\*.\\*                | ✅          |\n| v7.\\*.\\*       | v7.\\*.\\*                | On demand   |\n| v6.\\*.\\*       | v6.\\*.\\*                | ❌          |\n| v5.\\*.\\*       | v5.\\*.\\*                | ❌          |\n\n\u003e **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.\n\n## Install\n\n```bash\nnpm install @capgo/capacitor-screen-orientation\nnpx cap sync\n```\n\n## iOS Configuration\n\nTo detect physical device orientation using motion sensors on iOS, you need to add the Motion Usage Description to your `Info.plist`:\n\n```xml\n\u003ckey\u003eNSMotionUsageDescription\u003c/key\u003e\n\u003cstring\u003eThis app uses motion sensors to detect the true physical orientation of your device.\u003c/string\u003e\n```\n\n## Usage\n\n```typescript\nimport { ScreenOrientation } from '@capgo/capacitor-screen-orientation';\n\n// Get current orientation\nconst result = await ScreenOrientation.orientation();\nconsole.log('Current orientation:', result.type);\n\n// Lock to landscape\nawait ScreenOrientation.lock({ orientation: 'landscape' });\n\n// Lock UI orientation and track physical orientation via motion sensors\n// Note: UI will still respect user's orientation lock, but you'll get physical orientation events\nawait ScreenOrientation.lock({\n  orientation: 'portrait',\n  bypassOrientationLock: true\n});\n\n// Listen for orientation changes\nconst listener = await ScreenOrientation.addListener(\n  'screenOrientationChange',\n  (result) =\u003e {\n    console.log('Orientation changed:', result.type);\n  }\n);\n\n// Unlock orientation\nawait ScreenOrientation.unlock();\n\n// Start motion-based tracking to detect physical device orientation\n// This uses motion sensors to track how the device is actually held\nawait ScreenOrientation.startOrientationTracking({\n  bypassOrientationLock: true\n});\n\n// Check if device orientation lock is enabled\n// Compares physical device orientation (from sensors) with UI orientation (from system)\nconst lockStatus = await ScreenOrientation.isOrientationLocked();\nif (lockStatus.locked) {\n  console.log('Orientation lock is ON!');\n  console.log('Physical device orientation:', lockStatus.physicalOrientation);\n  console.log('UI orientation:', lockStatus.uiOrientation);\n} else {\n  console.log('Orientation lock is OFF or motion tracking not active');\n}\n\n// Stop motion-based tracking\nawait ScreenOrientation.stopOrientationTracking();\n\n// Remove listener\nawait listener.remove();\n```\n\n## API\n\n\u003cdocgen-index\u003e\n\n* [`orientation()`](#orientation)\n* [`lock(...)`](#lock)\n* [`unlock()`](#unlock)\n* [`startOrientationTracking(...)`](#startorientationtracking)\n* [`stopOrientationTracking()`](#stoporientationtracking)\n* [`isOrientationLocked()`](#isorientationlocked)\n* [`addListener('screenOrientationChange', ...)`](#addlistenerscreenorientationchange-)\n* [`removeAllListeners()`](#removealllisteners)\n* [`getPluginVersion()`](#getpluginversion)\n* [Interfaces](#interfaces)\n* [Type Aliases](#type-aliases)\n\n\u003c/docgen-index\u003e\n\n\u003cdocgen-api\u003e\n\u003c!--Update the source file JSDoc comments and rerun docgen to update the docs below--\u003e\n\nCapacitor Screen Orientation Plugin interface.\n\nProvides methods to detect and control screen orientation,\nwith support for detecting true physical device orientation using motion sensors.\n\n### orientation()\n\n```typescript\norientation() =\u003e Promise\u003cScreenOrientationResult\u003e\n```\n\nGet the current screen orientation.\n\nReturns the current orientation of the device screen.\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#screenorientationresult\"\u003eScreenOrientationResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### lock(...)\n\n```typescript\nlock(options: OrientationLockOptions) =\u003e Promise\u003cvoid\u003e\n```\n\nLock the screen orientation to a specific type.\n\nLocks the screen to the specified orientation.\nOn iOS, if bypassOrientationLock is true, it will also start\ntracking physical device orientation using motion sensors.\n\nNote: The UI will still respect the user's orientation lock setting.\nMotion tracking allows you to detect how the device is physically held\neven when the UI doesn't rotate.\n\n| Param         | Type                                                                      | Description                          |\n| ------------- | ------------------------------------------------------------------------- | ------------------------------------ |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#orientationlockoptions\"\u003eOrientationLockOptions\u003c/a\u003e\u003c/code\u003e | Options for locking the orientation. |\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### unlock()\n\n```typescript\nunlock() =\u003e Promise\u003cvoid\u003e\n```\n\nUnlock the screen orientation.\n\nAllows the screen to rotate freely based on device position.\nAlso stops any motion-based orientation tracking if it was enabled.\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### startOrientationTracking(...)\n\n```typescript\nstartOrientationTracking(options?: StartOrientationTrackingOptions | undefined) =\u003e Promise\u003cvoid\u003e\n```\n\nStart tracking device orientation using motion sensors.\n\nThis method is useful when you want to track the device's physical\norientation independently from the screen orientation lock.\nIt uses Core Motion on iOS to detect orientation changes.\n\n| Param         | Type                                                                                        | Description                                |\n| ------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------ |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#startorientationtrackingoptions\"\u003eStartOrientationTrackingOptions\u003c/a\u003e\u003c/code\u003e | Options for starting orientation tracking. |\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### stopOrientationTracking()\n\n```typescript\nstopOrientationTracking() =\u003e Promise\u003cvoid\u003e\n```\n\nStop tracking device orientation using motion sensors.\n\nStops the motion-based orientation tracking if it was started.\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### isOrientationLocked()\n\n```typescript\nisOrientationLocked() =\u003e Promise\u003cOrientationLockStatusResult\u003e\n```\n\nCheck if device orientation lock is currently enabled.\n\nThis method compares the physical device orientation (from motion sensors)\nwith the UI orientation. If they differ, orientation lock is enabled.\n\nNote: This requires motion tracking to be active via\nstartOrientationTracking() or lock() with bypassOrientationLock: true.\nWorks on both iOS (Core Motion) and Android (Accelerometer).\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#orientationlockstatusresult\"\u003eOrientationLockStatusResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### addListener('screenOrientationChange', ...)\n\n```typescript\naddListener(eventName: 'screenOrientationChange', listenerFunc: (result: ScreenOrientationResult) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\nListen for screen orientation changes.\n\nRegisters a listener that will be called whenever the screen orientation changes.\nIf motion-based tracking is enabled, this will also fire for orientation changes\ndetected by motion sensors even when orientation lock is enabled.\n\n| Param              | Type                                                                                             | Description                                         |\n| ------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- |\n| **`eventName`**    | \u003ccode\u003e'screenOrientationChange'\u003c/code\u003e                                                           | The event name. Must be 'screenOrientationChange'.  |\n| **`listenerFunc`** | \u003ccode\u003e(result: \u003ca href=\"#screenorientationresult\"\u003eScreenOrientationResult\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e | Callback function invoked when orientation changes. |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### removeAllListeners()\n\n```typescript\nremoveAllListeners() =\u003e Promise\u003cvoid\u003e\n```\n\nRemove all listeners for this plugin.\n\nRemoves all registered event listeners.\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### getPluginVersion()\n\n```typescript\ngetPluginVersion() =\u003e Promise\u003c{ version: string; }\u003e\n```\n\nGet the native plugin version.\n\nReturns the current version of the native plugin implementation.\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;{ version: string; }\u0026gt;\u003c/code\u003e\n\n**Since:** 1.0.0\n\n--------------------\n\n\n### Interfaces\n\n\n#### ScreenOrientationResult\n\nResult returned by the orientation() method.\n\n| Prop       | Type                                                        | Description                   | Since |\n| ---------- | ----------------------------------------------------------- | ----------------------------- | ----- |\n| **`type`** | \u003ccode\u003e\u003ca href=\"#orientationtype\"\u003eOrientationType\u003c/a\u003e\u003c/code\u003e | The current orientation type. | 1.0.0 |\n\n\n#### OrientationLockOptions\n\nOptions for locking the screen orientation.\n\n| Prop                        | Type                                                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Default            | Since |\n| --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |\n| **`orientation`**           | \u003ccode\u003e\u003ca href=\"#orientationlocktype\"\u003eOrientationLockType\u003c/a\u003e\u003c/code\u003e | The orientation type to lock to.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                    | 1.0.0 |\n| **`bypassOrientationLock`** | \u003ccode\u003eboolean\u003c/code\u003e                                                | Whether to track physical device orientation using motion sensors. When true, uses device motion sensors to detect the true physical orientation of the device, even when the device orientation lock is enabled. **Important:** This does NOT bypass the UI orientation lock. The screen will still respect the user's orientation lock setting. This option only affects orientation detection/tracking - you'll receive orientation change events based on how the device is physically held, but the UI will not rotate if orientation lock is enabled. Supported on iOS (Core Motion) and Android (Accelerometer). | \u003ccode\u003efalse\u003c/code\u003e | 1.0.0 |\n\n\n#### StartOrientationTrackingOptions\n\nOptions for starting orientation tracking using motion sensors.\n\n| Prop                        | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                         | Default            | Since |\n| --------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |\n| **`bypassOrientationLock`** | \u003ccode\u003eboolean\u003c/code\u003e | Whether to track physical device orientation using motion sensors. When true, uses device motion sensors to detect the true physical orientation of the device, even when the device orientation lock is enabled. **Important:** This does NOT bypass the UI orientation lock. This only enables detection of the physical orientation. Supported on iOS (Core Motion) and Android (Accelerometer). | \u003ccode\u003efalse\u003c/code\u003e | 1.0.0 |\n\n\n#### OrientationLockStatusResult\n\nResult returned by the isOrientationLocked() method.\n\n| Prop                      | Type                                                        | Description                                                                                                                                                                                                                                                                                                      | Since |\n| ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |\n| **`locked`**              | \u003ccode\u003eboolean\u003c/code\u003e                                        | Whether the device orientation lock is currently enabled. This is determined by comparing the physical device orientation (from motion sensors) with the UI orientation. If they differ, orientation lock is enabled. Available on iOS (Core Motion) and Android (Accelerometer) when motion tracking is active. | 1.0.0 |\n| **`physicalOrientation`** | \u003ccode\u003e\u003ca href=\"#orientationtype\"\u003eOrientationType\u003c/a\u003e\u003c/code\u003e | The physical orientation of the device from motion sensors. Available when motion tracking is active (iOS and Android).                                                                                                                                                                                          | 1.0.0 |\n| **`uiOrientation`**       | \u003ccode\u003e\u003ca href=\"#orientationtype\"\u003eOrientationType\u003c/a\u003e\u003c/code\u003e | The current UI orientation reported by the system.                                                                                                                                                                                                                                                               | 1.0.0 |\n\n\n#### PluginListenerHandle\n\n| Prop         | Type                                      |\n| ------------ | ----------------------------------------- |\n| **`remove`** | \u003ccode\u003e() =\u0026gt; Promise\u0026lt;void\u0026gt;\u003c/code\u003e |\n\n\n### Type Aliases\n\n\n#### OrientationType\n\nOrientation type that describes the orientation state of the device.\n\n\u003ccode\u003e'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'\u003c/code\u003e\n\n\n#### OrientationLockType\n\nOrientation lock type that can be used to lock the device orientation.\n\n\u003ccode\u003e'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'\u003c/code\u003e\n\n\u003c/docgen-api\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCap-go%2Fcapacitor-screen-orientation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCap-go%2Fcapacitor-screen-orientation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCap-go%2Fcapacitor-screen-orientation/lists"}