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.


Represents an object attached to a particular location (or a set of locations) on a map. Implemented by tile layers, markers, popups, image overlays, vector layers and layer groups.


Method Returns Description
onAdd( <Map> map ) - Should contain code that creates DOM elements for the overlay, adds them to map panes where they should belong and puts listeners on relevant map events. Called on map.addLayer(layer).
onRemove( <Map> map ) - Should contain all clean up code that removes the overlay's elements from the DOM and removes listeners previously added in onAdd. Called on map.removeLayer(layer).

Implementing Custom Layers

The most important things know about when implementing custom layers are Map viewreset event and latLngToLayerPoint method. viewreset is fired when the map needs to reposition its layers (e.g. on zoom), and latLngToLayerPoint is used to get coordinates for the layer's new position.

Another event often used in layer implementations is moveend which fires after any movement of the map (panning, zooming, etc.).

Another thing to note is that you'll usually need to add leaflet-zoom-hide class to the DOM elements you create for the layer so that it hides during zoom animation. Implementing zoom animation for custom layers is a complex topic and will be documented separately in future, but meanwhile you can take a look at how it's done for Leaflet layers (e.g. ImageOverlay) in the source.

Custom Layer Example

Here's how a custom layer implementation usually looks:

var MyCustomLayer = L.Class.extend({

	initialize: function (latlng) {
// save position of the layer or any options from the constructor
this._latlng = latlng;

	onAdd: function (map) {
this._map = map;

// create a DOM element and put it into one of the map panes
this._el = L.DomUtil.create('div', 'my-custom-layer leaflet-zoom-hide');

// add a viewreset event listener for updating layer's position, do the latter
map.on('viewreset', this._reset, this);

	onRemove: function (map) {
// remove layer's DOM elements and listeners
map.off('viewreset', this._reset, this);

	_reset: function () {
// update layer's position
var pos = this._map.latLngToLayerPoint(this._latlng);
L.DomUtil.setPosition(this._el, pos);

map.addLayer(new MyCustomLayer(latlng));