@capacitor/motion

The Motion API tracks accelerometer and device orientation (compass heading, etc.)

Install

npm install @capacitor/motion
npx cap sync

Permissions

This plugin is currently implemented using Web APIs. On iOS devices, permission must be requested before accessing device motion or orientation events. To request permission, prompt the user on any user-initiated action (such as a button click):

import { PluginListenerHandle } from '@capacitor/core';
import { Motion } from '@capacitor/motion';


let accelHandler: PluginListenerHandle;
let orientationHandler: PluginListenerHandle;

myAccelerationButton.addEventListener('click', async () => {
  if (typeof DeviceMotionEvent.requestPermission === 'function') {
    try {
      const permission = await DeviceMotionEvent.requestPermission();
      if (permission !== 'granted') return;
    } catch (e) {
      // Handle error
      return;
    }
  }

  // Once the user approves, can start listening:
  accelHandler = await Motion.addListener('accel', event => {
    console.log('Device motion event:', event);
  });
});

myOrientationButton.addEventListener('click', async () => {
  if (typeof DeviceOrientationEvent.requestPermission === 'function') {
    try {
      const permission = await DeviceOrientationEvent.requestPermission();
      if (permission !== 'granted') return;
    } catch (e) {
      // Handle error
      return;
    }
  }

  // Once the user approves, can start listening:
  orientationHandler = await Motion.addListener('orientation', event => {
    console.log('Device orientation event:', event);
  });
});

// Stop the acceleration listener
const stopAcceleration = () => {
  if (accelHandler) {
    accelHandler.remove();
  }
};

// Stop the orientation listener
const stopOrientation = () => {
  if (orientationHandler) {
    orientationHandler.remove();
  }
};

// Remove all listeners
const removeListeners = () => {
  Motion.removeAllListeners();
};

See the DeviceMotionEvent and DeviceOrientationEvent APIs to understand the data supplied in the 'accel' and 'orientation' events respectively.

API

• addListener('accel', ...)
• addListener('orientation', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

addListener('accel', ...)

addListener(eventName: 'accel', listenerFunc: AccelListener) => Promise<PluginListenerHandle>

Add a listener for accelerometer data

Param	Type
eventName	'accel'
listenerFunc	AccelListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('orientation', ...)

addListener(eventName: 'orientation', listenerFunc: OrientationListener) => Promise<PluginListenerHandle>

Add a listener for device orientation change (compass heading, etc.)

Param	Type
eventName	'orientation'
listenerFunc	OrientationListener

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all the listeners that are attached to this plugin.

Since: 1.0.0

---

Interfaces

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

AccelListenerEvent

Prop	Type	Description	Since
acceleration	Acceleration	An object giving the acceleration of the device on the three axis X, Y and Z. Acceleration is expressed in m/s	1.0.0
accelerationIncludingGravity	Acceleration	An object giving the acceleration of the device on the three axis X, Y and Z with the effect of gravity. Acceleration is expressed in m/s	1.0.0
rotationRate	RotationRate	An object giving the rate of change of the device's orientation on the three orientation axis alpha, beta and gamma. Rotation rate is expressed in degrees per seconds.	1.0.0
interval	number	A number representing the interval of time, in milliseconds, at which data is obtained from the device.	1.0.0

Acceleration

Prop	Type	Description	Since
x	number	The amount of acceleration along the X axis.	1.0.0
y	number	The amount of acceleration along the Y axis.	1.0.0
z	number	The amount of acceleration along the Z axis.	1.0.0

RotationRate

Prop	Type	Description	Since
alpha	number	The amount of rotation around the Z axis, in degrees per second.	1.0.0
beta	number	The amount of rotation around the X axis, in degrees per second.	1.0.0
gamma	number	The amount of rotation around the Y axis, in degrees per second.	1.0.0

Type Aliases

AccelListener

(event: AccelListenerEvent): void

OrientationListener

(event: RotationRate): void

OrientationListenerEvent

RotationRate