Legacy

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

<script>
// Provide your access token
L.mapbox.accessToken = '<your access token here>';
// Create a map in the div #map
L.mapbox.map('map', 'username.mapid');
</script>

Build anything with Mapbox.js,
a library for fast & interactive maps.

Built on top of Leaflet, an open source library.
Open source and available on GitHub.
Browser tested with IE8+ and all modern browsers.
mapbox.js v3.3.1 Get started 
<script src='https://api.mapbox.com/mapbox.js/v3.3.1/mapbox.js'></script>
<link href='https://api.mapbox.com/mapbox.js/v3.3.1/mapbox.css' rel='stylesheet' />
Include mapbox.js and CSS in your HTML header and call L.mapbox.map('map', 'mapbox.streets') to load your first map.
You are viewing an older version of Mapbox.js. Check out v3.3.1 for the latest.

API documentation

The Mapbox.js documentation is organized by methods. Each method is shown with potential arguments in a table. Objects returned by constructors are documented by just their object type. For instance, L.mapbox.featureLayer documents a function that returns a layer for markers. The methods on that object are then documented as featureLayer.setFilter, featureLayer.getGeoJSON, and so on.

To use this API, you'll need to understand basic Javascript and mapping concepts. If you'd like to learn Javascript, start with an interactive course or book. To learn more about maps, we've provided a helpful article explaining how web maps work.

Asynchronous calls and the `ready` event

Mapbox.js is asynchronous - when you create a layer like L.mapbox.tileLayer('mapbox.streets'), the layer doesn't immediately know which tiles to load and its attribution information. Instead, it loads the information in an AJAX call.

For most things you'll write, this isn't a problem, since Mapbox.js does a good job of handling these on-the-fly updates. If you're writing code that needs to know when layers and other dynamically-loaded objects are ready, you can use the ready event to listen for their ready state. For instance:

var layer = L.mapbox.tileLayer('mapbox.streets');
layer.on('ready', function() {
  // the layer has been fully loaded now, and you can
  // call .getTileJSON and investigate its properties
});

Similarly, dynamically-loaded objects produce an `error` event if something goes wrong:

var layer = L.mapbox.tileLayer('mapbox.streets');
layer.on('error', function(err) {
  // Handle error
});

Retina support

Mapbox.js automatically supports Retina screens like those found with Apple hardware and other high-density displays. When Mapbox.js detects that a user has a high-density screen, it will use high-density tiles and marker icons.