feat: add support for heading

Author: ItsChaceD

CHANGELOG.md

@@ -1,3 +1,12 @@
+# [8.1.0](https://github.com/ionic-team/capacitor-geolocation/compare/v8.0.0...v8.1.0) (2026-02-02)
+
+### Features
+
+* **heading:** Added support for accurate heading information across all platforms.
+* **heading:** The `heading` property on iOS, Android, and Web now prioritizes actual compass bearing (true/magnetic heading) when available, falling back to direction of travel (course).
+* **coords:** Added `magneticHeading`, `trueHeading`, `headingAccuracy`, and `course` to `Position.coords`.
+* **web:** Improved heading support using `DeviceOrientation` APIs.
+
 # [8.0.0](https://github.com/ionic-team/capacitor-geolocation/compare/v7.1.6...v8.0.0) (2025-12-08)
 
 

CapacitorGeolocation.podspec

@@ -13,6 +13,6 @@ Pod::Spec.new do |s|
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
   s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
-  s.dependency 'IONGeolocationLib', spec='2.0.0'
+  s.dependency 'IONGeolocationLib', '2.1.0'
   s.swift_version = '5.1'
 end

README.md

@@ -159,10 +159,10 @@ Not available on web.
 
 #### Position
 
-| Prop            | Type                                                                                                                                                                                | Description                                             | Since |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----- |
-| **`timestamp`** | <code>number</code>                                                                                                                                                                 | Creation timestamp for coords                           | 1.0.0 |
-| **`coords`**    | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; }</code> | The GPS coordinates along with the accuracy of the data | 1.0.0 |
+| Prop            | Type                                                                                                                                                                                                                                                                                                       | Description                                             | Since |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----- |
+| **`timestamp`** | <code>number</code>                                                                                                                                                                                                                                                                                        | Creation timestamp for coords                           | 1.0.0 |
+| **`coords`**    | <code>{ latitude: number; longitude: number; accuracy: number; altitudeAccuracy: number \| null; altitude: number \| null; speed: number \| null; heading: number \| null; magneticHeading: number \| null; trueHeading: number \| null; headingAccuracy: number \| null; course: number \| null; }</code> | The GPS coordinates along with the accuracy of the data | 1.0.0 |
 
 
 #### PositionOptions

android/build.gradle

@@ -81,7 +81,7 @@ dependencies {
         implementation project(':capacitor-android')
     }
 
-    implementation("io.ionic.libs:iongeolocation-android:2.1.0")
+    implementation("io.ionic.libs:iongeolocation-android:2.2.0")
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
 
     implementation 'com.google.code.gson:gson:2.13.2'

android/src/main/kotlin/com/capacitorjs/plugins/geolocation/GeolocationPlugin.kt

@@ -255,6 +255,10 @@ class GeolocationPlugin : Plugin() {
             locationResult.altitudeAccuracy?.let { put("altitudeAccuracy", it) }
             put("speed", locationResult.speed)
             put("heading", locationResult.heading)
+            locationResult.magneticHeading?.let { put("magneticHeading", it) }
+            locationResult.trueHeading?.let { put("trueHeading", it) }
+            locationResult.headingAccuracy?.let { put("headingAccuracy", it) }
+            locationResult.course?.let { put("course", it) }
         }
         return JSObject().apply {
             put("timestamp", locationResult.timestamp)

ios/Sources/GeolocationPlugin/GeolocationConstants.swift

@@ -33,5 +33,9 @@ enum Constants {
         static let speed: String = "speed"
         static let timestamp: String = "timestamp"
         static let altitudeAccuracy: String = "altitudeAccuracy"
+        static let magneticHeading: String = "magneticHeading"
+        static let trueHeading: String = "trueHeading"
+        static let headingAccuracy: String = "headingAccuracy"
+        static let course: String = "course"
     }
 }

ios/Sources/GeolocationPlugin/IONGLOCPositionModel+JSONTransformer.swift

@@ -10,9 +10,14 @@ extension IONGLOCPositionModel {
     }
 
     private var coordsJSObject: JSObject {
-        [
+        let headingValue = trueHeading != -1.0 ? trueHeading : (magneticHeading != -1.0 ? magneticHeading : course)
+        return [
             Constants.Position.altitude: altitude,
-            Constants.Position.heading: course,
+            Constants.Position.heading: headingValue != -1.0 ? headingValue : NSNull(),
+            Constants.Position.magneticHeading: magneticHeading != -1.0 ? magneticHeading : NSNull(),
+            Constants.Position.trueHeading: trueHeading != -1.0 ? trueHeading : NSNull(),
+            Constants.Position.headingAccuracy: headingAccuracy != -1.0 ? headingAccuracy : NSNull(),
+            Constants.Position.course: course,
             Constants.Position.accuracy: horizontalAccuracy,
             Constants.Position.latitude: latitude,
             Constants.Position.longitude: longitude,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capacitor/geolocation",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "The Geolocation API provides simple methods for getting and tracking the current position of the device using GPS, along with altitude, heading, and speed information if available.",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",
@@ -88,4 +88,4 @@
       "src": "android"
     }
   }
-}
+}

src/definitions.ts

@@ -140,11 +140,43 @@ export interface Position {
     speed: number | null;
 
     /**
-     * The heading the user is facing (if available)
+     * The heading the user is facing (if available).
+     *
+     * Historically, this field returned the direction of travel (course) on iOS and Android.
+     * It now prioritizes the compass heading (true or magnetic) if available, falling back
+     * to the direction of travel (course).
      *
      * @since 1.0.0
      */
     heading: number | null;
+
+    /**
+     * The heading (measured in degrees) relative to magnetic north.
+     *
+     * @since 8.1.0
+     */
+    magneticHeading: number | null | undefined;
+
+    /**
+     * The heading (measured in degrees) relative to true north.
+     *
+     * @since 8.1.0
+     */
+    trueHeading: number | null | undefined;
+
+    /**
+     * The maximum deviation (measured in degrees) between the reported heading and the true geomagnetic heading.
+     *
+     * @since 8.1.0
+     */
+    headingAccuracy: number | null | undefined;
+
+    /**
+     * The direction in which the device is travelling, measured in degrees and relative to due north.
+     *
+     * @since 8.1.0
+     */
+    course: number | null | undefined;
   };
 }
 

src/web.ts

@@ -10,13 +10,80 @@ import type {
 } from './definitions';
 
 export class GeolocationWeb extends WebPlugin implements GeolocationPlugin {
+  private latestOrientation: {
+    magneticHeading: number | null;
+    trueHeading: number | null;
+    headingAccuracy: number | null;
+  } | null = null;
+
+  constructor() {
+    super();
+    if (typeof window !== 'undefined') {
+      const win = window as any;
+      if ('ondeviceorientationabsolute' in win) {
+        win.addEventListener('deviceorientationabsolute', (event: any) => this.updateOrientation(event, true), true);
+      } else if ('ondeviceorientation' in win) {
+        win.addEventListener('deviceorientation', (event: any) => this.updateOrientation(event, false), true);
+      }
+    }
+  }
+
+  private updateOrientation(event: any, isAbsolute: boolean) {
+    let trueHeading: number | null = null;
+    let magneticHeading: number | null = null;
+    let headingAccuracy: number | null = null;
+
+    if (isAbsolute && event.alpha !== null) {
+      trueHeading = (360 - event.alpha) % 360;
+    } else if (event.webkitCompassHeading !== undefined && event.webkitCompassHeading !== null) {
+      magneticHeading = event.webkitCompassHeading;
+      headingAccuracy = event.webkitCompassAccuracy;
+    } else if (event.alpha !== null && event.absolute === true) {
+      trueHeading = (360 - event.alpha) % 360;
+    } else if (event.alpha !== null) {
+      magneticHeading = (360 - event.alpha) % 360;
+    }
+
+    if (trueHeading !== null || magneticHeading !== null) {
+      this.latestOrientation = {
+        trueHeading,
+        magneticHeading,
+        headingAccuracy,
+      };
+    }
+  }
+
+  private augmentPosition(pos: globalThis.GeolocationPosition): Position {
+    const coords = pos.coords;
+    const orientation = this.latestOrientation;
+
+    const heading = orientation?.trueHeading ?? orientation?.magneticHeading ?? coords.heading ?? null;
+
+    return {
+      timestamp: pos.timestamp,
+      coords: {
+        latitude: coords.latitude,
+        longitude: coords.longitude,
+        accuracy: coords.accuracy,
+        altitude: coords.altitude,
+        altitudeAccuracy: (coords as any).altitudeAccuracy,
+        speed: coords.speed,
+        heading: heading,
+        magneticHeading: orientation?.magneticHeading ?? null,
+        trueHeading: orientation?.trueHeading ?? null,
+        headingAccuracy: orientation?.headingAccuracy ?? null,
+        course: coords.heading ?? null,
+      },
+    };
+  }
+
   async getCurrentPosition(options?: PositionOptions): Promise<Position> {
     return new Promise((resolve, reject) => {
       navigator.geolocation.getCurrentPosition(
-        (pos) => {
-          resolve(pos);
+        pos => {
+          resolve(this.augmentPosition(pos));
         },
-        (err) => {
+        err => {
           reject(err);
         },
         {
@@ -31,10 +98,10 @@ export class GeolocationWeb extends WebPlugin implements GeolocationPlugin {
 
   async watchPosition(options: PositionOptions, callback: WatchPositionCallback): Promise<CallbackID> {
     const id = navigator.geolocation.watchPosition(
-      (pos) => {
-        callback(pos);
+      pos => {
+        callback(this.augmentPosition(pos));
       },
-      (err) => {
+      err => {
         callback(null, err);
       },
       {