A image viewer control for Mapbox GL JS

Usage no npm install needed!

<script type="module">
  import mapboxMapboxGlImageViewer from 'https://cdn.skypack.dev/@mapbox/mapbox-gl-image-viewer';


A generic Mapbox GL JS control for viewing and tagging images.


Add the JavaScript and CSS file from the package.

<script src="https://unpkg.com/@mapbox/mapbox-gl-image-viewer@1.0.11/dist/mapbox-gl-image-viewer.js" charset="utf-8"></script>
<link rel="stylesheet" href="https://unpkg.com/@mapbox/mapbox-gl-image-viewer@1.0.11/dist/mapbox-gl-image-viewer.css">

Or install the package from npm,

npm install --save @mapbox/mapbox-gl-image-viewer

and import the js and css files.

import MapboxImageViewer from '@mapbox/mapbox-gl-image-viewer/dist/mapbox-gl-image-viewer.js';
import '@mapbox/mapbox-gl-image-viewer/dist/mapbox-gl-image-viewer.css';


Create an instance of the control,

var imageViewer = new MapboxImageViewer({
  allowResize: true,
  allowTagCreate: true,
  allowTagDelete: true,
  allowTagSelect: true,
  defaultTags: ['trafficsign', 'stopsignal', 'noleftturn'],
  onTagCreate: function(tag) { console.log('created', tag); },
  onTagDelete: function(tag) { console.log('deleted', tag); },
  onTagSelect: function(tag) { console.log('selected', tag); },

and add it to the map.

map.addControl(imageViewer, 'bottom-left');


new MapboxImageViewer(config)

Create an instance of the image viewer. Returns imageViewer.


  • allowResize (boolean, default false) Allow image resizing?
  • allowTagCreate (boolean, default false) Allow creating new tags?
  • allowTagDelete (boolean, default false) Allow deleting existing tags?
  • allowTagSelect (boolen, default false) Allow selecting tags?
  • defaultTags (Array, default []) List of default tags that can be used when tagging.
  • aspectRatio (number, default NaN) The aspect ratio of a tag. Free-form by default.
  • onTagCreate (function, optional) Function called when a new tag is created. Receives a tag object.
  • onTagDelete (function, optional) Function called when an existing tag is deleted. Receives a tag object.
  • onTagSelect (function, optional) Function called when a tag is selected. Receives a tag object.

A tag object created by the control will be of the following structure.

{ id: 'b9bd77b70fd9285c0379e34deba33385', // unique id created for each tag
  x: 48, y: 86,                           // top-left coords of the tag wrt to the image
  width: 84, height: 84,                  // width and height of the tag
  name: 'trafficsign'                     // name, one of the set default tags

imageViewer.showImage(url, [tags])

Load an image and display it on the viewer. If an array of tags is provided, render them on the image.

    {id: 'b9bd77b70fd9285c0379e34deba33385', x: 48, y: 86, width: 84, height: 84, name: 'trafficsign'},
    {id: '0074efb305841c15a7f040442a4e3f14', x: 233, y: 26, width: 84, height: 84, name: 'stopsignal'},
    {id: '87f7dbd6e3b1156f6ffefe0f43ee1c9e', x: 217, y: 199, width: 116, height: 133, name: 'noleftturn'}


Hide the viewer.


See example/index.html for a working example.