Getting started with Mapbox.js

Note: Mapbox Editor has been deprecated. Your existing projects can be found here. For more information, see our announcement and guide to migrating a Mapbox Editor project.

If you’ve poked around the Mapbox website, you’ve seen some of the awesome maps that are being made with our tools. How did Foursquare and Pinterest make such cool custom markers? How does Roadtrippers get that neat buffer around their routes? How did GitHub get those sweet specialized tooltips?

All of them went beyond Mapbox Editor and used Mapbox.js. Mapbox.js is a JavaScript API that allows you to create and customize your maps to your exact specifications. If you’re running up against the feature limit in the Mapbox Editor, want your tooltips to open on hover, or would like to add marker clustering and filtering, you can do all of these things and much more with Mapbox.js.

A web mapping library

Mapbox.js is a web mapping library that extends the popular Leaflet.js library. A web mapping library allows you to add a map to a web page and define its basemap tiles, its data, and a variety of functionality. Think of it like a toolbox filled with many different map-making tools that can be used together to build beautiful and interactive custom experiences.

Mapbox.js boasts the power of Leaflet.js, but is also heavily integrated with the Mapbox stack. If you’ve created a custom style in Mapbox Studio Classic or built your own features with the Mapbox Editor, Mapbox.js has tools for building web maps with those layers that add additional functionality. For more information on how web maps work, read our How do web maps work? guide.

What Mapbox.js can do

Add a map to the page

The core function of Mapbox.js is adding a map to your HTML page. Using one line of JavaScript, you can add a map to your webpage with a basemap that pans and zooms, set to a specific location and zoom level.

<!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').setView([38.8929, -77.0252], 14);
</script>
</body>
</html>
View source

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

Extend Editor projects

Mapbox.js has some great built-in functionality for capturing data and styles from Projects you’ve created with the Mapbox Editor. You can add the project you’ve created and customize the pan bounds and zoom levels of your map, customize your tooltips, and more. Here’s an example of adding zoom restrictions to a Project created with the Mapbox Editor. Note that the tooltips from the Editor map are still intact!

<!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.dc-markers', {
  // the options here prevent mouse wheel or trackpad scrolling
  // and restrict the zooms to zoom levels 14 through 18
  scrollWheelZoom: false,
  maxZoom: 14,
  minZoom: 10
}).setView([38.8906, -77.01313], 12);
</script>
</body>
</html>
View source

If you just want to add and customize the data from your Project but want to use a different basemap layer, you can do that as well. In this example, we’re adding the data from a Mapbox Editor project to a different basemap and customizing the tooltips to include a link to Mapbox.com:

<!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>';
var map = L.mapbox.map('map-three', 'mapbox.light', {
  scrollWheelZoom: false,
  maxZoom: 18,
  minZoom: 12
}).setView([38.8906, -77.01313], 13);
var myLayer = L.mapbox.featureLayer('mapbox.dc-markers').addTo(map);
myLayer.on('layeradd', function(e) {
  var popupContent = '<strong>' + e.layer.feature.properties.title + '</strong> <br />This map created with <a href="https://mapbox.com">Mapbox</a>!';
  e.layer.bindPopup(popupContent);
});

</script>
</body>
</html>
View source

Add custom data

If you want to add your own data to your Mapbox.js map, you can! Mapbox.js supports a few different formats, including GeoJSON and KML.

In this example, we create a GeoJSON point in our code and add it to a Mapbox Dark 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.dark', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);

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

We can then style the data either by adding style properties to the GeoJSON or by using the handy pointToLayer option. In this example, we’re replacing the point with a red circleMarker:

<!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: {}
    }
  ]
};
var map = L.mapbox.map('map-five', 'mapbox.streets', {
  scrollWheelZoom: false
}).setView([38.8929, -77.0252], 14);

var myLayer = L.mapbox.featureLayer(geojson, {
  pointToLayer: function(feature, latlon) {
    return L.circleMarker(latlon, {
      fillColor: '#ff0000',
      fillOpacity: 0.8,
      stroke: false
    });
  }
}).addTo(map);
</script>
</body>
</html>
View source

For more information on using markers in Mapbox.js, check out our Markers and Mapbox.js guide.

Advanced interactivity

When it comes to customization and advanced interactivity, the possibilities with Mapbox.js are nearly endless. A great example is the store locator you can create by following our Building a store locator tutorial that includes custom markers and a lovely interactive sidebar:

View it live.

For more examples of advanced interactivity, check out all of the Mapbox.js examples.

Using Mapbox.js

Unlike Mapbox Editor, where you made all of your changes in the browser, Mapbox.js is a JavaScript library that you need to add to the HTML of a webpage. To create a webpage, you’ll need to use a text editor like Sublime Text 2 to write your code and then upload it to a webserver so it can be accessed on the internet. Two awesome ways to do this are to use GitHub Pages or Neocities. You can also test out your map with JS Bin.

As a JavaScript library, you can add Mapbox.js to your webpage in the <head> of your HTML document by copying and pasting the following code:

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

By adding this to your webpage, you have access to all of the functionality of Mapbox.js, from adding a basic map to your page to advanced styling and interaction.

Start building!

Ready to get started? We recommend walking through the Building a store locator guide and diving into the Mapbox.js examples.

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