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

You are viewing an older version of Mapbox.js. Check out v3.3.1 for the latest.

L.mapbox.gridLayer(id|url|tilejson, options)

An L.mapbox.gridLayer loads UTFGrid tiles of interactivity into your map, which you can easily access with L.mapbox.gridControl.

Options Value Description
id or url or tilejson (required) string if id or url object if tilejson
  • An id string examples.map-foo
  • A URL to TileJSON, like https://api.mapbox.com/v3/examples.map-0l53fhk2.json
  • A TileJSON object, from your own Javascript code
options Object The second argument is optional. If provided, it may include:


// the second argument is optional
var layer = L.mapbox.gridLayer('examples.map-20v6611k');

Returns a L.mapbox.gridLayer object.

Class: L.mapbox.GridLayer

gridLayer.on(event, handler, context)

Bind an event handler to a given event on this L.mapbox.gridLayer instance. GridLayers expose a number of useful events that give you access to UTFGrid data as the user interacts with the map.

Options Value Description
event (required) string the event name
handler (required) function a callback function run every time that the event is fired
context (optional) object the context of the handler function: this is the value of this when that function returns

After binding an event with .on, you can unbind it with .off, with the same argument structure.

The default events are:

  • click: mouse has clicked while on a feature in UTFGrid. Event has { latLng: location, data: featureData } as its data.
  • mouseover: mouse has moved onto a new feature in UTFGrid. Event has { latLng: location, data: featureData } as its data.
  • mousemove: mouse has moved within a feature in UTFGrid. Event has { latLng: location, data: featureData } as its data.
  • mouseout: mouse has moved from a feature to an area without any features. Event has { latLng: location, data: featureData } as its data, in which featureData is the feature data the mouse was previously on.


map.gridLayer.on('click', function(e) {
    if (e.data && e.data.url) {


Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.


var layer = L.mapbox.gridLayer('examples.map-20v6611k')
    // since layers load asynchronously through AJAX, use the
    // `.on` function to listen for them to be loaded before
    // calling `getTileJSON()`
    .on('ready', function() {
        // get TileJSON data from the loaded layer
        var TileJSON = layer.getTileJSON();

Returns: the TileJSON object

gridLayer.getData(latlng, callback)

Load data for a given latitude, longitude point on the map, and call the callback function with that data, if any.

Options Value Description
latlng object latlng a L.LatLng object
callback function callback a function that is called with the grid data as an argument

Returns: the L.mapbox.gridLayer object