maplibre-gl-compass

A heading-up compass for MapLibre GL JS 🧭

This plugin rotates the map based on the values from the Device orientation events.
Therefore, it can only be used on devices equipped with an orientation sensor, such as mobile devices.

Demo page is here.

Installation

npm install maplibre-gl-compass

Usage

Basic usage

import { Map } from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'
import { CompassControl } from 'maplibre-gl-compass'
import 'maplibre-gl-compass/style.css'

const map = new Map({/* YOUR_MAP_OPTION */})

map.addControl(new CompassControl())

Advanced usage

import { Map } from 'maplibre-gl'
import 'maplibre-gl/dist/maplibre-gl.css'
import { CompassControl } from 'maplibre-gl-compass'
import type { CompassEvent, CompassError } from 'maplibre-gl-compass'
import 'maplibre-gl-compass/style.css'

const map = new Map({/* YOUR_MAP_OPTION */})

const compass = new CompassControl({
  debug: true,    // Show debug view. Default is false.
  visible: true,  // Show compass button. Default is true.
  timeout: 10000, // The maximum time to wait for a DeviceOrientationEvent. Default is 3000 [ms].
})

compass.on('turnon', () => {
  // Set pitch when compass is turned on.
  map.setPitch(45)
})

compass.on('turnoff', () => {
  // Restore pitch and north up when compass is turned off
  map.setPitch(0)
  map.setBearing(0)
})

compass.on('compass', (event: CompassEvent) => {
  // Your custom logic is here!
})

compass.on('error', (event: CompassError) => {
  // Your custom logic is here!
})

map.addControl(compass)

Options

| name | default | description | | ------- | ------- | ---------------------------------------------------------- | | debug | false | Show debug view. | | visible | true | Show compass button. | | timeout | 3000 | The maximum time[ms] to wait for a DeviceOrientationEvent. |

Events

| name | description | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | turnon | Fired when the compass is turned on. | | turnoff | Fired when the compass is turned off. | | error | Fired when the compass cannot be accessed due to permission denied or a timeout. | | compass | Fired when the device orientation changes. A heading number represents the difference between the motion of the device around the z axis of the world system and the direction of the north, expressed in degrees with values ranging from 0 to 360. |

Reference

• https://developer.apple.com/documentation/webkitjs/deviceorientationevent
• https://developer.mozilla.org/en-US/docs/Web/API/Window/deviceorientationabsolute_event

License

This project is licensed under the terms of the MIT license.