Help
All docschevron-rightHelpchevron-rightarrow-leftTutorialschevron-rightExtend with Mapbox.js

Extend with Mapbox.js

Intermediate
JavaScript
Prerequisite

Familiarity with front-end development concepts.

alert
LEGACY

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 Mapbox 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.
  • 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.1/mapbox.js'></script>
<link href='https://api.mapbox.com/mapbox.js/v3.2.1/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-v12, 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>
const map = L.mapbox.map('map')
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));
</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>
const map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));
</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>
const map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));
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.io writes and displays GeoJSON for you.

Add a marker

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

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

Now you have the marker on the map:

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

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

const 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>
const 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": {}
    }
  ]
};
const map = L.mapbox.map('map')
  .setView([38.8929, -77.0252], 14)
  .addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));
map.scrollWheelZoom.disable();  

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

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

const 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.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Demo: Extend with Mapbox.js</title>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script src="https://api.mapbox.com/mapbox.js/v3.2.1/mapbox.js"></script>
<link
href="https://api.mapbox.com/mapbox.js/v3.2.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" class="map"></div>
<script>
L.mapbox.accessToken = '<your access token here>';
const 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
}
}
]
};
 
const map = L.mapbox
.map('map')
.setView([38.8929, -77.0252], 14)
.addLayer(L.mapbox.styleLayer('mapbox://styles/mapbox/streets-v12'));
map.scrollWheelZoom.disable();
 
const 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>
</body>
</html>

Next steps

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

Join the Mapbox Developers Discord Communityarrow-right