intermediate
JavaScript
Translate your web maps from the Google Maps JavaScript API to Mapbox
Prerequisite
Familiarity with front-end development concepts.

Are you using Google Maps and looking for the best way to start making the switch to Mapbox? You’ve come to the right place! This tutorial will walk you through how to use Mapbox GL JS, a web mapping JavaScript library, to create a web map, add a marker, and attach a popup using similar methods you may be used to working with when using the Google Maps JavaScript API.

Getting started

This guide assumes that you are already familiar with the Google Maps JavaScript API V3 and basic front-end web development knowledge including HTML, CSS, and JavaScript.

There are a few resources you’ll need to get started:

mapboxgl.accessToken = '<your access token here>';
  • Mapbox GL JS. You’ll need the latest versions of the Mapbox GL JS javascript and CSS files. You can link directly to the Mapbox hosted versions by copying this snippet into the head of your HTML document.
<script src='https://api.mapbox.com/mapbox-gl-js/v0.38.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v0.38.0/mapbox-gl.css' rel='stylesheet' />
  • A text editor. You’ll be writing HTML, CSS, and JavaScript.

Initializing a web map

First, set up an HTML file and add the above JavaScript and CSS files to the head. Once you’ve got your HTML file set up, head to the next step.

Google

With the Google Maps JavaScript API, you can initialize a new map with JavaScript as shown below:

var map = new google.maps.Map(document.getElementById('map'), {
  mapTypeId: 'roadmap',
  center: { lat: 64.1436456, lng: -21.9270884 },
  zoom: 13
});

Mapbox GL JS

With Mapbox GL JS, you can initialize a map in a similar way. The result of the sample code below is a map that uses the Mapbox Streets template style, initialized at a set zoom level and coordinates. The style option below is set to the style URL for Mapbox Streets, one of our template styles:

var map = new mapboxgl.Map({
  container: 'map', // HTML container id
  style: 'mapbox://styles/mapbox/streets-v9', // style URL
  center: [-21.9270884, 64.1436456], // starting position as [lng, lat]
  zoom: 13
});

You can also use custom styles created with Mapbox Studio, or you can change your map’s style dynamically in the browser at runtime, depending on your needs.

Adding a marker

Now you’re ready to add a single marker to your map.

Google

With the Google Maps JavaScript API, you can add a marker to a map as shown below:

var map = new google.maps.Map(document.getElementById('map'), {
  mapTypeId: 'roadmap',
  center: { lat: 64.1436456, lng: -21.9270884 },
  zoom: 13
});

var marker = new google.maps.Marker({
  position: { lat: 64.1436456, lng: -21.9270884 },
  title: 'Reykjavik Roasters - Coffee Shop',
  map: map
});

Mapbox GL JS

There are a number of ways you can add markers to a map in Mapbox GL JS. The example below includes an HTML div element styled with CSS:

var map = new mapboxgl.Map({
  container: 'map', // HTML container id
  style: 'mapbox://styles/mapbox/streets-v9', // style URL
  center: [-21.9270884, 64.1436456], // starting position as [lng, lat]
  zoom: 13
});

var el = document.createElement('div');

var marker = new mapboxgl.Marker(el, { offset: [-10, -10] })
.setLngLat([-21.9270884, 64.1436456])
.addTo(map);

The code above creates an empty div with the class mapboxgl-marker and adds it to your map. Using CSS, you can to use any shapes, colors, or images as a marker on your map. The following CSS rules result in a simple circle with a border:

.mapboxgl-marker {
  height: 16px;
  width: 16px;
  background-color: #ff8280;
  border: 3px solid white;
  border-radius: 50%;
}

You can also attach markers to a set of points by loading a GeoJSON source or a vector tileset source.

Adding interactivity

No marker is complete without a popup. In the next steps, add a popup that appears and displays information when the marker is clicked.

Google

In the Google Maps JavaScript API, interactive popups are go by the name InfoWindow and are added like this:

var map = new google.maps.Map(document.getElementById('map'), {
  mapTypeId: 'roadmap',
  center: { lat: 64.14356426, lng: -21.92661562 },
  zoom: 13
});

var marker = new google.maps.Marker({
  position: { lat: 64.14356426, lng: -21.92661562 },
  map: map
});

var infowindow = new google.maps.InfoWindow({
  content: '<h3>Reykjavik Roasters</h3><p>A good coffee shop</p>'
});

marker.addListener('click', function() {
  infowindow.open(map, marker);
});

Mapbox GL JS

In Mapbox GL JS, you can attach the popup directly to the marker and it will be displayed when the marker is clicked by default. No need to add an event listener. Here’s how you add a popup and populate it with some HTML content:

var map = new mapboxgl.Map({
  container: 'map', // HTML container id
  style: 'mapbox://styles/mapbox/streets-v9', // style URL
  center: [-21.92661562, 64.14356426], // starting position as [lng, lat]
  zoom: 13
});

var popup = new mapboxgl.Popup()
.setHTML('<h3>Reykjavik Roasters</h3><p>A good coffee shop</p>');

var el = document.createElement('div');

var marker = new mapboxgl.Marker(el, { offset: [-11, -11] })
.setLngLat([-21.92661562, 64.14356426])
.setPopup(popup)
.addTo(map);

Next steps

Congratulations! You’ve made a web map with a marker and popup with Mapbox GL JS. Be sure to check out our other Mapbox GL JS tutorials for more ways to build on your map:

Dive in further by checking out Mapbox GL JS documentation and examples!