Tutorials
intermediate
JavaScript

Extend with Mapbox.js

Prerequisite

Familiarity with front-end development concepts.

Note

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 you through how to use 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 tileset ID. You can use a tileset ID from a default Mapbox Style or from your own Mapbox Studio Classic project. You can find your project's tileset 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.2.0/mapbox.js'></script>
<link href='https://api.mapbox.com/mapbox.js/v3.2.0/mapbox.css' rel='stylesheet' />

To use a Mapbox map style with Mapbox.js, you also need a style URL. We put a placeholder in for you, mapbox://styles/mapbox/streets-v11, but you can swap it out with the style URL for another Mapbox map style or create your own custom style with Mapbox Studio.

<div id='map' class='map'> </div>
<script>
<script>
var map = L.mapbox.map('map')
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
</script>

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.map() so that your map opens up to Washington, DC.

<div id='map' class='map'> </div>
<script>
var map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
</script>

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.

<div id='map-three' class='map'> </div>
<script>
var map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
map.scrollWheelZoom.disable();  
</script>

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 help, geojson.net 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:

<div id='map' class='map'> </div>
<script>
var geojson = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [-77.0366048812866, 38.89784666877921]
      },
      properties: {}
    }
  ]
};
var map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
map.scrollWheelZoom.disable();  

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

If you have a lot of features, you'll want to move the GeoJSON to its 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 gray 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:

<div id='map' class='map'> </div>
<script>
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')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
map.scrollWheelZoom.disable();  

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

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": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.00905323028564,
          38.88981361419182
        ]
      },
      "properties": {}
    },
    {
      "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": {}
    }
  ]
}

Here's how your new styled features look on the map:

<div id='map' class='map'> </div>
<script>
var geojson = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.0366048812866,
          38.89784666877921
        ]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.00905323028564,
          38.88981361419182
        ]
      },
      "properties": {}
    },
    {
      "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": {}
    }
  ]
};
var map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
map.scrollWheelZoom.disable();  

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

Add a legend

Legends describe data on a map. Mapbox.js allows you to add a legend with L.mapbox.legendControl.addLegend('Legend content'). The addLegend() method takes 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:

<div id='map' class='map'> </div>
<script>
var geojson = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.0366048812866,
          38.89784666877921
        ]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -77.00905323028564,
          38.88981361419182
        ]
      },
      "properties": {}
    },
    {
      "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": {}
    }
  ]
};

var map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v11'));
map.scrollWheelZoom.disable();

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

L.mapbox.legendControl({ position: 'topright' }).addLegend('<strong>My walk from the White House to the hill!</strong>').addTo(map);
</script>

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

Explore the Mapbox.js examples page for more ideas and code to help you further customize your Mapbox.js projects.

Was this page helpful?