@capgo/capacitor-compass

Native compass heading plugin for Capacitor.

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

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

Install

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

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

API

• getCurrentHeading()
• getPluginVersion()
• startListening()
• stopListening()
• addListener('headingChange', ...)
• removeAllListeners()
• checkPermissions()
• requestPermissions()
• Interfaces
• Type Aliases

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() => 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 events.

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------ | | eventName | 'headingChange' | - The event to listen for ('headingChange') | | listenerFunc | (event: HeadingChangeEvent) => void | - The function to call when the event is emitted |

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

Since: 7.0.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

Interfaces

CompassHeading

Result containing the compass heading value.

| Prop | Type | Description | | ----------- | ------------------- | ---------------------------------- | | value | number | Compass heading in degrees (0-360) |

HeadingChangeEvent

Event data for heading change events.

| Prop | Type | Description | | ----------- | ------------------- | ---------------------------------- | | value | number | Compass heading in degrees (0-360) |

PermissionStatus

Permission status for compass plugin.

| Prop | Type | Description | Since | | ------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | compass | PermissionState | Permission state for accessing compass/location data. On iOS, this requires location permission to access heading. On Android, no special permissions are required for compass sensors. | 7.0.0 |

Type Aliases

PermissionState

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

Credits

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