@capgo/capacitor-compass

Get the device compass heading in degrees on iOS and Android, as a one-off reading or a live stream. Point users toward a place, rotate a map or build a qibla finder.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-compass in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-compass to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Current heading: getCurrentHeading() returns the heading in degrees.
• Live updates: startListening() emits headingChange events, stopListening() stops them.
• Accuracy: watchAccuracy(), getAccuracy() and the accuracyChange event so you can ask users to calibrate.
• Permissions: checkPermissions() and requestPermissions().
• Platforms: iOS and Android. iOS uses Core Location heading, Android uses the device sensors. Not available on web.

Why Capacitor Compass?

The official Capacitor Motion API relies on web APIs for compass/heading data, which provides a suboptimal developer experience:

• Inconsistent behavior across platforms
• Additional permissions handling through web APIs
• Limited accuracy compared to native implementations
• Poor performance on some devices
• No accuracy monitoring to ensure reliable compass readings

This plugin provides true native compass functionality using:

• iOS: CLLocationManager for accurate heading data via CoreLocation
• Android: Hardware sensors (accelerometer + magnetometer) for precise bearing calculation
• Accuracy monitoring: Monitor compass accuracy on Android and prompt users to calibrate when needed
• Event-based API: Modern addListener pattern for real-time heading updates

Essential for navigation apps, augmented reality, location-based games, and any app needing accurate compass heading.

Compatibility

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.

Install

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

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/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 @capgo/capacitor-compass
npx cap sync

Requirements

iOS

Add the following to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need access to your location to determine compass heading</string>

Android

No additional setup required. The plugin uses the device's accelerometer and magnetometer sensors.

Usage

import { CapgoCompass, CompassAccuracy } from '@capgo/capacitor-compass';

// Get current heading once
const { value } = await CapgoCompass.getCurrentHeading();
console.log('Current heading:', value, 'degrees');

// Listen for continuous heading updates
const handle = await CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value, 'degrees');
});

// Start the compass sensor
await CapgoCompass.startListening();

// Monitor compass accuracy (Android only)
const accuracyHandle = await CapgoCompass.addListener('accuracyChange', (event) => {
  console.log('Compass accuracy:', event.accuracy);
  if (event.accuracy < CompassAccuracy.MEDIUM) {
    console.log('Compass needs calibration');
    // Show your own custom UI to prompt user to calibrate
  }
});

// Start accuracy monitoring
await CapgoCompass.watchAccuracy();

// Get current accuracy
const { accuracy } = await CapgoCompass.getAccuracy();
console.log('Current accuracy:', accuracy);

// Later: stop listening
await CapgoCompass.stopListening();
await CapgoCompass.unwatchAccuracy();
await handle.remove();
await accuracyHandle.remove();

API

• getCurrentHeading()
• getPluginVersion()
• startListening(...)
• stopListening()
• addListener('headingChange', ...)
• addListener('accuracyChange', ...)
• removeAllListeners()
• checkPermissions()
• requestPermissions()
• watchAccuracy()
• unwatchAccuracy()
• getAccuracy()
• Interfaces
• Type Aliases
• Enums

Capacitor Compass Plugin interface for reading device compass heading.

getCurrentHeading()

getCurrentHeading() => Promise<CompassHeading>

Get the current compass heading in degrees. On iOS, the heading is updated in the background, and the latest value is returned. On Android, the heading is calculated when the method is called using accelerometer and magnetometer sensors. Not implemented on Web.

Returns: Promise<CompassHeading>

Since: 7.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 7.0.0

startListening(...)

startListening(options?: ListeningOptions | undefined) => Promise<void>

Start listening for compass heading changes via events. This starts the compass sensors and emits 'headingChange' events.

Since: 7.0.0

stopListening()

stopListening() => Promise<void>

Stop listening for compass heading changes. This stops the compass sensors and stops emitting events.

Since: 7.0.0

addListener('headingChange', ...)

addListener(eventName: 'headingChange', listenerFunc: (event: HeadingChangeEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Add a listener for compass heading change events.

Returns: Promise<{ remove: () => Promise<void>; }>

Since: 7.0.0

addListener('accuracyChange', ...)

addListener(eventName: 'accuracyChange', listenerFunc: (event: AccuracyChangeEvent) => void) => Promise<{ remove: () => Promise<void>; }>

Add a listener for compass accuracy change events. Only supported on Android. On iOS and Web, this will never emit events.

Returns: Promise<{ remove: () => Promise<void>; }>

Since: 8.2.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 7.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the current permission status for accessing compass data. On iOS, this checks location permission status. On Android, this always returns 'granted' as no permissions are required.

Returns: Promise<PermissionStatus>

Since: 7.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to access compass data. On iOS, this requests location permission (required for heading data). On Android, this resolves immediately as no permissions are required.

Returns: Promise<PermissionStatus>

Since: 7.0.0

watchAccuracy()

watchAccuracy() => Promise<void>

Start monitoring compass accuracy. On Android, this monitors the magnetometer accuracy and emits accuracyChange events. Developers can listen to these events and implement their own UI for calibration prompts. On iOS and Web, this method does nothing as compass accuracy monitoring is not available.

Since: 8.2.0

unwatchAccuracy()

unwatchAccuracy() => Promise<void>

Stop monitoring compass accuracy. This stops the accuracy monitoring.

Since: 8.2.0

getAccuracy()

getAccuracy() => Promise<{ accuracy: CompassAccuracy; }>

Get the current compass accuracy level. On Android, returns the current magnetometer sensor accuracy. On iOS and Web, always returns CompassAccuracy.UNKNOWN as accuracy monitoring is not available.

Returns: Promise<{ accuracy: CompassAccuracy; }>

Since: 8.2.0

Interfaces

CompassHeading

Result containing the compass heading value.

ListeningOptions

Options for configuring compass listening behavior.

HeadingChangeEvent

Event data for heading change events.

AccuracyChangeEvent

Event data for accuracy change events.

PermissionStatus

Permission status for compass plugin.

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Enums

CompassAccuracy

Credits

This plugin is inspired by capacitor-native-compass by HeyItsBATMAN.