Legacy
Mapbox.js is no longer in active development. To learn more about our newer mapping tools see Mapbox GL JS.
Build anything with Mapbox.js,
a library for fast & interactive maps.
<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' />
L.mapbox.map('map', 'mapbox.streets')
to load your first map. View simple example
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.