Maplair

an open-source JavaScript library
for building powerful interactive maps

← Tutorials

Overlays

There are 3 overlays in the Maplair API:

In this tutorial, you’ll learn how to use these overlays.

ImageOverlay

ImageOverlay is used to load and display a single image over specific bounds of the map.

To add an image overlay ImageOverlay use this:

const imageOverlay = new ImageOverlay(imageUrl, latLngBounds, options);

Creating a Map

First of all, create a Maplair map and add a background TileLayer in the usual way:

const map = new MaplairMap('map').setView([37.8, -96], 4);

const osm = new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
	maxZoom: 19,
	attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
}).addTo(map);

Let’s create an image overlay with multiple options:

const imageUrl = 'https://maps.lib.utexas.edu/maps/historical/newark_nj_1922.jpg';
const errorOverlayUrl = 'https://cdn-icons-png.flaticon.com/512/110/110686.png';
const altText = 'Image of Newark, N.J. in 1922. Source: The University of Texas at Austin, UT Libraries Map Collection.';
const latLngBounds = new LatLngBounds([[40.799311, -74.118464], [40.68202047785919, -74.33]]);

const imageOverlay = new ImageOverlay(imageUrl, latLngBounds, {
	opacity: 0.8,
	errorOverlayUrl: errorOverlayUrl,
	alt: altText,
	interactive: true
}).addTo(map);

If you want to see the area which is covered by the ImageOverlay, you can add a Rectangle with the same LatLngBounds to the map:

const rectangle = new Rectangle(latLngBounds).addTo(map);
map.fitBounds(latLngBounds);

You can find other options of ImageOverlay in the documentation.

See this example stand-alone.

VideoOverlay

Video used to be a hard task when building a webpage, until the <video> HTML element became widely supported.

Nowadays, we can easily embed videos using the following HTML code:

<video width="500" controls>
	<source src="https://www.mapbox.com/bites/00188/patricia_nasa.webm" type="video/webm">
	<source src="https://www.mapbox.com/bites/00188/patricia_nasa.mp4" type="video/mp4">
</video>

To display this video:

If a video can be shown in a webpage in this way, then Maplair can display it inside a map. It is important that the videos are prepared in such a way that they will fit the map: The video should have a “north-up” orientation, and its proportions should fit the map. If not, it will look out of place.

Creating a Map

First of all, create a Maplair map and add a background TileLayer in the usual way:

const map = new MaplairMap('map').setView([37.8, -96], 4);

const osm = new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', {
	maxZoom: 19,
	attribution: '© <a href="http://www.openstreetmap.org/copyright">OpenStreetMap</a>'
}).addTo(map);

Adding the Video Overlay

Adding a video overlay works very similar to adding an image overlay.

For a video overlay, just:

const videoUrls = [
	'https://www.mapbox.com/bites/00188/patricia_nasa.webm',
	'https://www.mapbox.com/bites/00188/patricia_nasa.mp4'
];
const errorOverlayUrl = 'https://cdn-icons-png.flaticon.com/512/110/110686.png';
const latLngBounds = new LatLngBounds([[32, -130], [13, -100]]);

const videoOverlay = new VideoOverlay(videoUrls, latLngBounds, {
	opacity: 0.8,
	errorOverlayUrl: errorOverlayUrl,
	interactive: true,
	autoplay: true,
	muted: true,
	playsInline: true
}).addTo(map);

And just like that, you’ll get the video on your map:

See this example stand-alone.

You can find other options of VideoOverlay in the documentation.

Video overlays behave like any other Maplair layer - you can add and remove them, let the user select from several videos using a layers control, etc.

A Bit of Control over the Video

If you read the API documentation, you’ll notice that the VideoOverlay class does not have a play() or pause() method.

For this, the getElement() method of the video overlay is useful. It returns the HTMLVideoElement (which inherits from HTMLMediaElement) for the overlay - and that has methods like play() and pause(), e.g.

videoOverlay.getElement().pause();

This allows us to build custom interfaces. For example, we can build a small subclass of Control to play/pause this video overlay once it’s loaded:

videoOverlay.on('load', function () {
	class MyPauseControl extends Control {
		onAdd() {
			const button = DomUtil.create('button');
			button.title = 'Pause';
			button.innerHTML = '<span aria-hidden="true">⏸</span>';
			DomEvent.on(button, 'click', function () {
				videoOverlay.getElement().pause();
			});
			return button;
		}
	}
	class MyPlayControl extends Control {
		onAdd() {
			const button = DomUtil.create('button');
			button.title = 'Play';
			button.innerHTML = '<span aria-hidden="true">▶️</span>';
			DomEvent.on(button, 'click', function () {
				videoOverlay.getElement().play();
			});
			return button;
		}
	}

	const pauseControl = (new MyPauseControl()).addTo(map);
	const playControl = (new MyPlayControl()).addTo(map);
});
See this example stand-alone.

SVGOverlay

SVGOverlay is used to load, display and provide DOM access to an SVG file over specific bounds of the map.

To add an SVG overlay SVGOverlay use this:

const svgOverlay = new SVGOverlay(SVGElement, svgElementBounds, options);

It instantiates an image overlay object given an SVG element and the geographical bounds it is tied to. A viewBox attribute is required on the SVG element to zoom in and out properly.

Creating an SVG Element

Let’s create an SVG element:

const svgElement = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
svgElement.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
svgElement.setAttribute('viewBox', '0 0 200 200');
svgElement.innerHTML = '<rect width="200" height="200"/><rect x="75" y="23" width="50" height="50" style="fill:red"/><rect x="75" y="123" width="50" height="50" style="fill:#0013ff"/>';

Alternatively, you can create the SVG element in HTML code:

<svg id="svg" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200"><rect width="200" height="200"/><rect x="75" y="23" width="50" height="50" style="fill:red"/><rect x="75" y="123" width="50" height="50" style="fill:#0013ff"/></svg>

And choose this SVG element by using a querySelector:

const svgElement = document.querySelector('#svg');

Adding the SVG Overlay

Create the SVGOverlay with desired options similarly to ImageOverlay and VideoOverlay:

const latLngBounds = new LatLngBounds([[32, -130], [13, -100]]);
map.fitBounds(latLngBounds);

const svgOverlay = new SVGOverlay(svgElement, latLngBounds, {
	opacity: 0.7,
	interactive: true
}).addTo(map);

Although SVGOverlay does not have its own unique options, it inherits a variety of options from ImageOverlay, Interactive layer and Layer. Check out the documentation to find out more SVGOverlay options.

See this example stand-alone.