Capacitor Gyroscope Plugin

Capacitor plugin to read the device's gyroscope sensor.

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.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.
• 🤝 Compatibility: Works alongside the Accelerometer, Barometer and Pedometer plugins.

Missing a feature? Just open an issue 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 |

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

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:

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:

<key>NSMotionUsageDescription</key>
<string>The app needs to access the motion activity.</string>

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:

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):

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:

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:

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:

import { Gyroscope } from '@capawesome/capacitor-gyroscope';

const removeAllListeners = async () => {
  await Gyroscope.removeAllListeners();
};

API

• checkPermissions()
• getMeasurement()
• isAvailable()
• requestPermissions()
• startMeasurementUpdates()
• stopMeasurementUpdates()
• addListener('measurement', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check if the app has permission to access the gyroscope sensor.

Returns: Promise<PermissionStatus>

Since: 0.1.0

getMeasurement()

getMeasurement() => Promise<GetMeasurementResult>

Get the latest measurement.

This method returns the most recent measurement from the gyroscope sensor.

Returns: Promise<Measurement>

Since: 0.1.0

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check if the gyroscope sensor is available on the device.

Returns: Promise<IsAvailableResult>

Since: 0.1.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to access the gyroscope sensor.

Returns: Promise<PermissionStatus>

Since: 0.1.0

startMeasurementUpdates()

startMeasurementUpdates() => Promise<void>

Start emitting measurement events.

Since: 0.1.0

stopMeasurementUpdates()

stopMeasurementUpdates() => Promise<void>

Stop emitting measurement events.

Since: 0.1.0

addListener('measurement', ...)

addListener(eventName: 'measurement', listenerFunc: (event: MeasurementEvent) => void) => Promise<PluginListenerHandle>

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()

removeAllListeners() => Promise<void>

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).

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: Capture the acceleration force along the x, y, and z axes.
• Barometer: Obtain the static air pressure measured in hectopascals (hPa).
• Compass: Read the device compass heading.
• 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.

Changelog

See CHANGELOG.md.

License

See LICENSE.