--- title: Capacitor Gyroscope Plugin description: Capacitor plugin to read the device's gyroscope sensor with real-time rotation rate measurements. Supports Android, iOS, and the web. tags: - Android - iOS - Web search: boost: 2 faq: true status: new github_repo: capawesome-team/capacitor-plugins npm_package: "@capawesome/capacitor-gyroscope" --- # Capacitor Gyroscope Plugin Capacitor plugin to read the device's gyroscope sensor.
Deliver Live Updates to your Capacitor app with Capawesome Cloud
## Features The Capacitor Gyroscope plugin is one of the most complete motion sensing solutions for Capacitor apps. Here are some of the key features: - 🖥️ **Cross-platform**: Supports Android and iOS. - ⚡ **Real-time measurements**: Continuous gyroscope data with event listeners. - 📊 **Rotation rate**: Accurate x, y, and z-axis rotation rate in rad/s. - 🔒 **Permission handling**: Built-in permission management for sensor access. - 🤝 **Compatibility**: Works alongside the [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/), [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/) and [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/) plugins. - 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. - 🔁 **Up-to-date**: Always supports the latest Capacitor version. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases The Gyroscope plugin is typically used whenever an app needs to react to the rotation of the device, for example: - **Motion-controlled games**: Use the real-time rotation rate to steer a character or vehicle by tilting the device. - **Immersive experiences**: Rotate 360° views or augmented reality scenes based on the device's rotation. - **Gesture detection**: Detect rotation gestures such as twisting the device to trigger actions in your app. - **Motion analysis**: Record the rotation rate around the x, y, and z axes to analyze movement patterns. ## Compatibility | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | >=8.x.x | Active support | ## Guides - [The Complete Guide to Capacitor Device Sensors](https://capawesome.io/blog/capacitor-device-sensors-guide/): How rotation data powers tilt-to-steer game mechanics and AR features together with the Accelerometer. ## Installation You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash npx skills add capawesome-team/skills --skill capacitor-plugins ``` Then use the following prompt: ``` Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-gyroscope` plugin in my project. ``` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: ```bash npm install @capawesome/capacitor-gyroscope npx cap sync ``` ### Android #### Proguard If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: ``` -keep class io.capawesome.capacitorjs.plugins.** { *; } ``` ### iOS #### Privacy Descriptions Add the `NSMotionUsageDescription` key to the `ios/App/App/Info.plist` file, which tells the user why your app needs access to the device's motion data: ```xml NSMotionUsageDescription The app needs to access the motion activity. ``` ## Configuration No configuration required for this plugin. ## Usage The following examples show how to check if the gyroscope is available, get a single measurement, receive continuous measurement updates, check and request permissions, and remove all listeners. ### Check if the gyroscope is available Check whether the device has a gyroscope sensor before using the other methods: ```typescript import { Gyroscope } from '@capawesome/capacitor-gyroscope'; const isAvailable = async () => { const result = await Gyroscope.isAvailable(); return result.available; }; ``` ### Get a single measurement Get the most recent measurement from the gyroscope sensor. The rotation rate around the x, y, and z axes is reported in radians per second (rad/s): ```typescript import { Gyroscope } from '@capawesome/capacitor-gyroscope'; const getMeasurement = async () => { const measurement = await Gyroscope.getMeasurement(); console.log('X: ', measurement.x); console.log('Y: ', measurement.y); console.log('Z: ', measurement.z); }; ``` ### Receive continuous measurement updates Add a listener for the `measurement` event and start the measurement updates to receive the rotation rate in real time. The `measurement` event is only available on Android and iOS: ```typescript import { Gyroscope } from '@capawesome/capacitor-gyroscope'; const startMeasurementUpdates = async () => { await Gyroscope.addListener('measurement', measurement => { console.log('X: ', measurement.x); console.log('Y: ', measurement.y); console.log('Z: ', measurement.z); }); await Gyroscope.startMeasurementUpdates(); }; const stopMeasurementUpdates = async () => { await Gyroscope.stopMeasurementUpdates(); }; ``` ### Check and request permissions Check and request the permission to access the gyroscope sensor: ```typescript import { Gyroscope } from '@capawesome/capacitor-gyroscope'; const checkPermissions = async () => { const result = await Gyroscope.checkPermissions(); return result; }; const requestPermissions = async () => { const result = await Gyroscope.requestPermissions(); return result; }; ``` ### Remove all listeners Remove all listeners when you no longer need them: ```typescript import { Gyroscope } from '@capawesome/capacitor-gyroscope'; const removeAllListeners = async () => { await Gyroscope.removeAllListeners(); }; ``` ## API * [`checkPermissions()`](#checkpermissions) * [`getMeasurement()`](#getmeasurement) * [`isAvailable()`](#isavailable) * [`requestPermissions()`](#requestpermissions) * [`startMeasurementUpdates()`](#startmeasurementupdates) * [`stopMeasurementUpdates()`](#stopmeasurementupdates) * [`addListener('measurement', ...)`](#addlistenermeasurement-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### checkPermissions() ```typescript checkPermissions() => Promise ``` Check if the app has permission to access the gyroscope sensor. **Returns:** Promise<PermissionStatus> **Since:** 0.1.0 -------------------- ### getMeasurement() ```typescript getMeasurement() => Promise ``` Get the latest measurement. This method returns the most recent measurement from the gyroscope sensor. **Returns:** Promise<Measurement> **Since:** 0.1.0 -------------------- ### isAvailable() ```typescript isAvailable() => Promise ``` Check if the gyroscope sensor is available on the device. **Returns:** Promise<IsAvailableResult> **Since:** 0.1.0 -------------------- ### requestPermissions() ```typescript requestPermissions() => Promise ``` Request permission to access the gyroscope sensor. **Returns:** Promise<PermissionStatus> **Since:** 0.1.0 -------------------- ### startMeasurementUpdates() ```typescript startMeasurementUpdates() => Promise ``` Start emitting `measurement` events. **Since:** 0.1.0 -------------------- ### stopMeasurementUpdates() ```typescript stopMeasurementUpdates() => Promise ``` Stop emitting `measurement` events. **Since:** 0.1.0 -------------------- ### addListener('measurement', ...) ```typescript addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise ``` Called when a new measurement is available. Only available on Android and iOS. | Param | Type | | ------------------ | ----------------------------------------------------------------------- | | **`eventName`** | 'measurement' | | **`listenerFunc`** | (event: Measurement) => void | **Returns:** Promise<PluginListenerHandle> **Since:** 0.1.0 -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise ``` Remove all listeners for this plugin. **Since:** 0.1.0 -------------------- ### Interfaces #### PermissionStatus | Prop | Type | Description | Since | | --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- | ----- | | **`gyroscope`** | GyroscopePermissionState | The permission status of the gyroscope sensor. | 0.1.0 | #### Measurement | Prop | Type | Description | Since | | ------- | ------------------- | ------------------------------------------------------------------ | ----- | | **`x`** | number | The rotation rate around the x-axis in radians per second (rad/s). | 0.1.0 | | **`y`** | number | The rotation rate around the y-axis in radians per second (rad/s). | 0.1.0 | | **`z`** | number | The rotation rate around the z-axis in radians per second (rad/s). | 0.1.0 | #### IsAvailableResult | Prop | Type | Description | Since | | --------------- | -------------------- | -------------------------------------------------------- | ----- | | **`available`** | boolean | Whether the gyroscope sensor is available on the device. | 0.1.0 | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | () => Promise<void> | ### Type Aliases #### GyroscopePermissionState PermissionState | 'limited' #### PermissionState 'prompt' | 'prompt-with-rationale' | 'granted' | 'denied' #### GetMeasurementResult Measurement #### MeasurementEvent Measurement ## FAQ ### How is this plugin different from other similar plugins? It delivers accurate x, y, and z-axis rotation rate in rad/s with both one-off readings via `getMeasurement()` and continuous real-time updates via the `measurement` event, plus built-in permission handling for sensor access on Android and iOS. The API is fully typed and actively maintained against the latest Capacitor and OS versions, and it pairs cleanly with our Accelerometer, Barometer, and Pedometer plugins so a single, consistent motion-sensing story is covered. If you only need an occasional reading, a simpler setup is perfectly fine; if you need continuous, low-level rotation data, this plugin is built for exactly that. ### Which platforms does the plugin support? The plugin supports Android and iOS. The continuous `measurement` event is only emitted on Android and iOS, so there is no gyroscope support in the browser. ### What units are the measurements reported in? Each measurement contains the rotation rate around the x, y, and z axes in radians per second (rad/s). ### What is the difference between `getMeasurement` and the `measurement` event? The `getMeasurement()` method returns the most recent measurement from the gyroscope sensor once. If you need continuous real-time updates instead, add a listener for the `measurement` event and call `startMeasurementUpdates()`. Call `stopMeasurementUpdates()` when you no longer need updates. ### Do I need any permissions to read the gyroscope? The plugin provides the `checkPermissions()` and `requestPermissions()` methods to manage access to the gyroscope sensor. On iOS, you also have to add the `NSMotionUsageDescription` key to your `Info.plist` file, which tells the user why your app needs access to the device's motion data (see [Installation](#installation)). ### How do I know if the device has a gyroscope sensor? Call the `isAvailable()` method. It returns whether the gyroscope sensor is available on the device, so you can hide or disable motion features on devices without a gyroscope. ### Can I use this plugin with Ionic, React, Vue or Angular? Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins - [Accelerometer](https://capawesome.io/docs/sdks/capacitor/accelerometer/): Capture the acceleration force along the x, y, and z axes. - [Barometer](https://capawesome.io/docs/sdks/capacitor/barometer/): Obtain the static air pressure measured in hectopascals (hPa). - [Compass](https://capawesome.io/docs/sdks/capacitor/compass/): Read the device compass heading. - [Pedometer](https://capawesome.io/docs/sdks/capacitor/pedometer/): Retrieve motion data such as the number of steps and the distance traveled. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/gyroscope/CHANGELOG.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/gyroscope/LICENSE).