Layer-Like Objects#

The ipyleaflet.Map.add() method supports “layer-like” objects; meaning any object with an as_leaflet_layer method. This interface can be especially useful for downstream developers who want their users to more easily be able to add their objects to an ipyleaflet.Map.


Downstream objects should implement an as_leaflet_layer method that returns an ipyleaflet type capable of being added to the Map.

Here is a simple example of creating a custom data class to hold heatmap data (coordinates with some numerical value).

import numpy as np

class MyHeatMap:
    def __init__(self, points, values, radius=20):
        self.points = points
        self.values = values
        self.radius = radius

    def data(self):
        return np.column_stack((self.points, self.values))

    def as_leaflet_layer(self):
        from ipyleaflet import Heatmap
        return Heatmap(

We can now use that custom data class and because it has an as_leaflet_layer interface, we can pass the object directly to ipyleaflet.Map.add().

from ipyleaflet import Map

n = 1000
data = MyHeatMap(
    np.random.uniform(-80, 80, (n, 2)),
    np.random.uniform(0, 1000, n),

m = Map(center=(0, 0), zoom=2)

External Examples#

The following external libraries are working to implement this new interface

  • localtileserver: a dynamic tile server built for visualizing large geospatial images/rasters with ipyleaflet.

  • xarray-leaflet: an xarray extension for tiled map plotting, based on ipyleaflet.