Capacitor plugin for reading the device compass heading.

• 🧭 Heading: Read the current compass heading on demand.
• 🔄 Live updates: Listen for continuous heading changes.
• 🌍 True north: Read the true (geographic) north heading on iOS.
• 🤝 Compatibility: Works alongside the Accelerometer, Barometer and Gyroscope 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 and we'll take a look!

The Compass plugin is typically used whenever an app needs to know which direction the device is pointing, for example:

• Compass apps: Build a classic compass UI that rotates with live heading updates.
• Navigation: Rotate a map or show the direction the user is currently facing.
• Outdoor activities: Guide hikers or geocachers towards a target bearing.
• Points of interest: Point the user towards a fixed geographic direction, such as a landmark or a prayer direction.

• The Complete Guide to Capacitor Device Sensors: How heading data fits into navigation and wayfinding features.

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-compass` 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-compass
npx cap sync

This plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented.

The magnetic heading is available without any permission. To also read the true (geographic) north heading, location services must be enabled and the NSLocationWhenInUseUsageDescription key must be added to the Info.plist file of your app.

<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to determine the true (geographic) north heading.</string>

If the key is missing or location permission is not granted, the trueHeading value is null.

No configuration required for this plugin.

The following examples show how to check if the compass sensor is available, read the current heading, and listen for heading changes.

Before reading the heading, you can check whether the device has a compass sensor. Only available on Android and iOS:

import { Compass } from '@capawesome/capacitor-compass';

const isAvailable = async () => {
  const { available } = await Compass.isAvailable();
  return available;
};

Get the most recent heading reading from the device's compass sensor. The result contains the magnetic heading, the true (geographic) heading if available, and the accuracy. Only available on Android and iOS:

import { Compass } from '@capawesome/capacitor-compass';

const getHeading = async () => {
  const heading = await Compass.getHeading();
  return heading;
};

Call startHeadingUpdates() to start emitting headingChange events and add a listener to receive continuous heading updates, for example to rotate a compass UI. Stop the updates when you no longer need them. Only available on Android and iOS:

import { Compass } from '@capawesome/capacitor-compass';

const startHeadingUpdates = async () => {
  await Compass.startHeadingUpdates();
};

const addHeadingChangeListener = async () => {
  await Compass.addListener('headingChange', heading => {
    console.log(heading);
  });
};

const stopHeadingUpdates = async () => {
  await Compass.stopHeadingUpdates();
};

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

• getHeading()
• isAvailable()
• startHeadingUpdates()
• stopHeadingUpdates()
• addListener('headingChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

getHeading() => Promise<GetHeadingResult>

Get the current device heading.

This method returns the most recent heading reading from the device's compass sensor.

Only available on Android and iOS.

Returns: Promise<Heading>

Since: 0.1.0

isAvailable() => Promise<IsAvailableResult>

Check if the compass sensor is available on the device.

Only available on Android and iOS.

Returns: Promise<IsAvailableResult>

Since: 0.1.0

startHeadingUpdates() => Promise<void>

Start emitting headingChange events.

Only available on Android and iOS.

Since: 0.1.0

stopHeadingUpdates() => Promise<void>

Stop emitting headingChange events.

Only available on Android and iOS.

Since: 0.1.0

addListener(eventName: 'headingChange', listenerFunc: (event: HeadingChangeEvent) => void) => Promise<PluginListenerHandle>

Add a listener for heading changes.

Only available on Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 0.1.0

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Only available on Android and iOS.

Since: 0.1.0

Heading

Heading

It reads the device compass heading both on demand and as a continuous stream of updates, returning the magnetic heading, the accuracy, and — on iOS with location services — the true geographic heading. An isAvailable() check lets you confirm the sensor is present before you rely on it, and the whole surface is fully typed. It supports CocoaPods and Swift Package Manager on iOS and is actively maintained against the latest Capacitor version, giving you consistent heading data across Android and iOS.

The magneticHeading value is the heading relative to magnetic north, while the trueHeading value is the heading relative to true (geographic) north. Both range from 0 to 360 degrees. The magnetic heading is always available, whereas the true heading can only be determined on iOS and may be null.

On Android, the true heading is not supported and the value is always null. On iOS, reading the true heading requires location services to be enabled and the NSLocationWhenInUseUsageDescription key to be added to your app's Info.plist file, as described in the Installation section. If the key is missing or location permission is not granted, the value is null.

No, this plugin is only available on Android and iOS. On the Web, all methods reject as unimplemented. You can use the isAvailable() method to check whether the compass sensor is available on the current device.

The magnetic heading is available without any permission on both Android and iOS. Only if you also want to read the true (geographic) north heading on iOS, location services must be enabled and the NSLocationWhenInUseUsageDescription key must be present in your Info.plist file.

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.

• Accelerometer: Capture the acceleration force along the x, y, and z axes.
• Barometer: Obtain the static air pressure measured in hectopascals.
• Gyroscope: Read the device's gyroscope sensor.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

See CHANGELOG.md.

See LICENSE.