intermediate
JavaScript
Extend with Mapbox.js
Prerequisite
Familiarity with front-end development concepts.

Mapbox.js is no longer in active development. To learn more about our newer mapping tools see Add custom markers in Mapbox GL JS.

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. You can use a map ID from a default Mapbox Style or from your own Mapbox Studio Classic project. You can find your project’s map ID by visiting your Classic projects page. It’s not covered in this guide, but you can add a Mapbox Studio style to your Mapbox.js map by following these instructions.
  • 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 document:

<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' />

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>

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

You can copy and paste the source code into your text editor to view and edit the example locally. 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 can swap it out with one of your own. Every Project you make with Mapbox Studio Classic and upload to your account has a Map ID. With Mapbox.js you can reference that map and make your styled map interactive – all with your Map ID.

Coordinates

Now that you’ve loaded your map tiles, set the initial location and zoom level to show our map when the page is loaded. You can do this by adding setView to L.mapbox.map() so that your 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>

Disable mouse zooming

Scrolling down a page that has a map can cause unwanted scroll zooming. For this guide, disable that interaction by setting scrollWheelZoom to false. Notice that you can’t scroll zoom on the map anymore.

<!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>

Add data

You can add data to our map to help tell a story, show a feature’s location, or visualize a trend. Mapbox.js supports a few different formats, including GeoJSON, KML, and CSV. In this example, you’ll start 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 and displays GeoJSON for you.

Add a marker

Store the GeoJSON as a variable called geojson and create a featureLayer to add it to the map.

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

Now you 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 = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [-77.0366048812866, 38.89784666877921]
      },
      properties: {}
    }
  ]
};
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>

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

Style data

The default grey style is rather boring, but you can customize it! You can specify your own styles within "properties": {} attribute 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 your GeoJSON looks like with 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 = {
  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'
      }
    }
  ]
};
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>

Click on the marker to see the tooltip!

Add a line

Make your map a little more interesting by adding another marker and a line to connect them.

Add a marker and line with set styles to our existing GeoJSON.

{
  "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
      }
    }
  ]
}

Your 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 = {
  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
      }
    }
  ]
};
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>

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'). The addLegend() method takes basic HTML code as an argument, so feel free to customize your legend to fit your needs!

By default, legends appear at the bottom right of a map. Since you’re working in a small space, 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 = {
  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
      }
    }
  ]
};

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>

Finished product

You did it! This guide covered a lot and we hope you leave feeling equipped with skills and tools to build your own custom projects.

Next steps

Be sure to check out the Mapbox.js examples page for more ideas and code to help you further customize your Mapbox.js projects.