Extend with Mapbox.js

In the Sharing your map guide, we described ways of quickly publishing a map using a share URL or embedding maps on a website. But what if you want to extend the interactivity even further?

This guide walks through the basics of Mapbox.js, a JavaScript API for rendering maps and creating custom interactions.

Getting started

For this guide you will need:

  • Your API access token. If you’re logged in, we automatically added your token to the examples in this guide. You can also find your access token on your account page.
  • A map ID. Use your own personalized map by getting a map ID from any of your Projects in your Classic projects page.
  • Your favorite text editor. You’ll be writing some HTML and JavaScript, after all.

Initialize a map

First, you’ll need the latest version of Mapbox.js. You can link directly to the Mapbox hosted version by copying this snippet into your HTML:

<script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
<link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />

We’re going to start by creating a blank HTML page. Here’s the simplest example to put a map on a page:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-one' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
L.mapbox.map('map-one', 'mapbox.streets');
</script>
</body>
</html>
View source

Click the View source button to toggle on the code used for each example.

You can copy and paste the source code into your text editor. If you’re not logged in, be sure to replace <your access token here> with your own access token.

Map ID

When working with Mapbox.js, you need to specify a Map ID. We put a placeholder in for you, mapbox.streets, but you should swap it out.

Remember your first map? Every Project you made with Mapbox Editor or upload to your Mapbox account has a Map ID. With Mapbox.js you can reference that map and make your styled map interactive – all with your Map ID.

Set coordinates

Let’s give this map a specific geographic coordinate in the world by adding setView to L.mapbox.map().

And now our map opens up to Washington, DC:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-two' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
L.mapbox.map('map-two', 'mapbox.streets').setView([38.8929, -77.0252], 14);
</script>
</body>
</html>
View source

Disable mouse zooming

Scrolling down a page that has a map can cause unwanted scroll zooming. For the purpose of this guide, let’s disable that interaction by setting scrollWheelZoom to false.

Try scroll zooming on the map (you can’t!):

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-three' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
L.mapbox.map('map-three', 'mapbox.streets', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);
</script>
</body>
</html>
View source

Add data

We can add data to our map to help tell a story. Mapbox.js supports a few different formats, including GeoJSON, KML, and CSV.

Let’s kick it off with GeoJSON.

GeoJSON

GeoJSON is a format for storing geometric shapes and marker positions. Here’s what a single point looks like in GeoJSON:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.0366048812866,
          38.89784666877921
        ]
      },
      "properties": {}
    }
  ]
}

Does GeoJSON look like hieroglyphics to you? Don’t sweat it. Once you learn the patterns, it becomes easier to write. If you need some help, there’s an awesome tool called geojson.io that writes GeoJSON for you.

Add a marker

Let’s store the GeoJSON as an array called geojson and create a featureLayer to add it to the map.

var myLayer = L.mapbox.featureLayer().addTo(map);
myLayer.setGeoJSON(geojson);

Now we have the marker on the map:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-four' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var geojson = {
  /* GeoJSON Point from above */
};
var map = L.mapbox.map('map-four', 'mapbox.streets', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);

var myLayer = L.mapbox.featureLayer().addTo(map);
myLayer.setGeoJSON(geojson);
</script>
</body>
</html>
View source

If you have a lot of features, then you’ll want to move the GeoJSON to it’s own file. You can then load the URL by specifying the path. You can also load a file from a remote source like Github.

Style data

The default grey style is rather boring, let’s customize it. You can specify your own styles within "properties": {} found in the GeoJSON. Styles are defined according to Simplestyle rules. You can learn more about the supported property names by browsing the specification.

You can also add a title in the properties object to create a tooltip over the feature.

Here’s what our GeoJSON looks like with the styles and a title added to the marker:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.0366048812866,
          38.89784666877921
        ]
      },
      "properties": {
        "title": "The White House",
        "marker-color": "#9c89cc",
        "marker-size": "medium",
        "marker-symbol": "building"
      }
    }
  ]
}

And here’s the styled marker on the map:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-five' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var geojson = {
  /* GeoJSON Point with style properties from above */
};
var map = L.mapbox.map('map-five', 'mapbox.streets', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);

var myLayer = L.mapbox.featureLayer().addTo(map);
myLayer.setGeoJSON(geojson);
</script>
</body>
</html>
View source

Click on the marker to see the tooltip!

Add a line

Let’s make our map a little more interesting by adding another marker and a line to connect them.

We’ll add the marker and line to the GeoJSON along with some styles:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.0366048812866,
          38.89784666877921
        ]
      },
      "properties": {
        "title": "The White House",
        "marker-color": "#9c89cc",
        "marker-size": "medium",
        "marker-symbol": "building"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.00905323028564,
          38.88981361419182
        ]
      },
      "properties": {
        "title": "U.S. Capitol",
        "marker-color": "#9c89cc",
        "marker-size": "medium",
        "marker-symbol": "town-hall"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [ -77.0366048812866, 38.89873175227713],
          [-77.03364372253417, 38.89876515143842],
          [-77.03364372253417, 38.89549195896866],
          [-77.02982425689697, 38.89549195896866],
          [-77.02400922775269, 38.89387200688839],
          [-77.01519012451172, 38.891416957534204],
          [-77.01521158218382, 38.892068305429156],
          [-77.00813055038452, 38.892051604275686],
          [-77.00832366943358, 38.89143365883688],
          [-77.00818419456482, 38.89082405874451],
          [-77.00815200805664, 38.88989712255097]
        ]
      },
      "properties": {
        "stroke": "#fa946e",
        "stroke-opacity": 1,
        "stroke-width": 6
      }
    }
  ]
}

Our new styled features look fantastic on the map:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-six' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var geojson = {
  /* GeoJSON with marker and line from above */
};
var map = L.mapbox.map('map-six', 'mapbox.streets', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);

var myLayer = L.mapbox.featureLayer().addTo(map);
myLayer.setGeoJSON(geojson);
</script>
</body>
</html>
View source

Add a legend

Legends are great for describing data on a map. Mapbox.js allows you to add a legend with map.legendControl.addLegend('Legend content').

By default, legends appear at the bottom right of a map. Since we’re working in a small space, let’s nudge the legend up by setting position: 'topright' when the map is initialized.

The legend now appears on the map:

<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-seven' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var geojson = {
  /* GeoJSON with marker and line from above */
};
var map = L.mapbox.map('map-seven', 'mapbox.streets', {
  scrollWheelZoom: false,
  legendControl: {
    position: 'topright'
  }
}).setView([38.8929, -77.0252], 14);

var myLayer = L.mapbox.featureLayer().addTo(map);
myLayer.setGeoJSON(geojson);

map.legendControl.addLegend('<strong>My walk from the White House to the hill!</strong>');
</script>
</body>
</html>
View source

Next steps

You did it! This guide covered a lot and we hope you leave feeling equipped with the right tools to expand on your ideas.

Be sure to check out Mapbox examples as it’s a great resource for learning more about specific interactions.

Next article:

Build indoor floorplans with Mapbox

Additional questions? Ask our support team or learn more about How Mapbox Works.