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.