compass-ts

TypeScript library to get and track device heading using the DeviceOrientationEvent API. Supports both standard browsers and iOS (with permission handling).

[!NOTE] Requires HTTPS or localhost to access motion sensors.

On iOS Safari, requestIOSPermission() must be called inside a user gesture handler (like onclick).

Heading accuracy depends on the device’s magnetometer and surrounding environment.

🔗 Demo:

You can test the live demo here: 🔗 Compass Demo Site

✨ Features

• ✅ Simple API to get heading once or watch continuously

• 📱 Works with iOS and Android (with built-in permission helper for iOS)

• ⚡ Zero dependencies

📦 Installation

Node.js

npm i compass-ts

Deno

deno add jsr:@hidaka/compass-ts

🚀 Usage

Get a single heading value

import { Compass } from "compass-ts";
// import import { Compass } from "@hidaka/compass-ts";

const compass = new Compass();

if (compass.isAPISupported()) {
  const heading = await compass.once();
  console.log("Current heading:", heading);
} else {
  console.error("Compass API not supported on this device.");
}

Observe heading changes in real time

const compass = new Compass();

compass.start((heading) => {
  console.log("Heading:", heading);
});

// Stop watching when done
setTimeout(() => {
  compass.stop();
  console.log("Stopped observing.");
}, 5000);

Handle iOS permission

On iOS (Safari), the user must explicitly grant permission to access motion data. Call this function in response to a user gesture (e.g., a button click).

const compass = new Compass();

const granted = await compass.requestIOSPermission();

if (granted) {
  console.log("iOS motion permission granted");
} else {
  console.log("Permission denied");
}

🧠 API Reference

new Compass()

Creates a new compass instance.

isAPISupported(): boolean

Checks whether the current environment supports DeviceOrientationEvent.

once(): Promise<number>

Retrieves the device heading once (in degrees, 0–360°).

start(callback: (heading: number) => void): void

Starts watching for heading updates. Calls callback with the current heading.

stop(): void

Stops watching for heading updates.

requestIOSPermission(): Promise<boolean>

Requests motion permission on iOS. Must be called in response to a user gesture (e.g., click/tap).

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.