--- layout: api title: "v2.1.5 JavaScript Library: L.mapbox.gridLayer(id|url|tilejson, options)" categories: api version: v2.1.5 permalink: /api/v2.1.5/l-mapbox-gridlayer ---

## 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 `{{site.tileApi}}/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: `accessToken`: Mapbox API access token. Overrides `L.mapbox.accessToken` for this layer.

Example:

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

Example:

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

### gridLayer.getTileJSON()

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

Example:

    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