Maplibre compass pro

Professional, good looking compass, suitable for use in all kinds of maplibre-based projects, inspired by Jack Sparrow's compass.

LIVE DEMO

Main features:

• old fashioned compass rose
• predefined sizes (from 'xs' to 'xl')
• typescript support
• possibility to visualize pitch
• possibility to display cardinal directions
• ease integration with maplibre-gl

Integration with maplibre

import 'maplibre-gl/dist/maplibre-gl.css'
import 'maplibre-compass-pro/dist/style.css'
import maplibregl from 'maplibre-gl'
import { Compass } from 'maplibre-compass-pro'

const map = new maplibregl.Map({
	container: 'map',
	style: '/mapStyle.json',
	center: [14.5, 53.4],
	zoom: 11,
})

const compass = new Compass({ size: 'sm' })
map.addControl(compass, 'bottom-left')

Remember to import compass styles 🙏🙏🙏 Compass props:

type CompassProps = {
	size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' // default 'md'
	visualizePitch?: boolean // default false
	displayDirections?: boolean // default false (use cardinal directions instead of needle)
	onClick?: () => void // default map.resetNorthPitch
}

You can omit props object so that all defaults will be used.

Using compass API

It's possible to update compass size, or toggle between needle/cardinal directions using its API. See code snippet below:

const compass = new Compass({ size: 'sm' }) // set size 'sm' as initial value, needle is used as default
map.addControl(compass, 'bottom-left')

// change compass size
compass.changeSize('lg')

// display cardinal directions instead of needle
compass.toggle()
// back to needle in 3 seconds
setTimeout(() => {
	compass.toggle()
}, 3000)

Integration with React

If you're working in React environment consider using react-map-gl as maplibre wrapper, together with map-gl-compass-pro. As for now there are tiny differences between those 2 packages (in view only) - but they will be aligned soon. It's also possible to wrap maplibre-compass-pro with use-control hook.

import 'maplibre-compass-pro/dist/style.css'

import { Compass as CompassPro } from 'maplibre-compass-pro'
import { useControl } from 'react-map-gl'

export function Compass() {
	useControl(() => new CompassPro({ size: 'md', displayDirections: true }), {
		position: 'bottom-left',
	})
	return null
}

This component has to be a child of Map component.

Placement

Compass position is determined by second argument of addControl function. You can pick one of: top-left, top-right, bottom-left, and bottom-right. Default position is bottom-left. If you want to move the compass away from the corner please override maplibre class, like below:

.maplibregl-ctrl-bottom-left {
	left: 10px;
	bottom: 10px;
}