Skip to content



The top-level class used to display a map in a Jupyter Widget.


import geopandas as gpd
from lonboard import Map, ScatterplotLayer, SolidPolygonLayer

# A GeoDataFrame with Point geometries
point_gdf = gpd.GeoDataFrame()
point_layer = ScatterplotLayer.from_geopandas(
    get_fill_color=[255, 0, 0],

# A GeoDataFrame with Polygon geometries
polygon_gdf = gpd.GeoDataFrame()
polygon_layer = SolidPolygonLayer.from_geopandas(
    get_fill_color=[255, 0, 0],

m = Map([point_layer, polygon_layer])


    layers: Union[BaseLayer, Sequence[BaseLayer]], **kwargs: Unpack[MapKwargs]
) -> None

Create a new Map.

Aside from the layers argument, pass keyword arguments for any other attribute defined in this class.



  • None

    A Map object.


as_html() -> HTML

Render the current map as a static HTML file in IPython.


The primary, recommended way to display a map is by leaving it as the last line in a cell.

from lonboard import Map

m = Map(layers=[])

This method exists to support environments that are unable to display Jupyter Widgets. Some aspects of Lonboard are unavailable with this display method. In particular, the map is unable to send any information back to Python. So selected_index will never be populated, for example.


  • HTML

    IPython HTML object.

basemap_style class-attribute instance-attribute

basemap_style = BasemapUrl(PositronNoLabels)

A URL to a MapLibre-compatible basemap style.

Various styles are provided in lonboard.basemap.


    longitude: Union[int, float],
    latitude: Union[int, float],
    zoom: Union[int, float],
    duration: int = 4000,
    pitch: Union[int, float] = 0,
    bearing: Union[int, float] = 0,
    curve: Optional[Union[int, float]] = None,
    speed: Optional[Union[int, float]] = None,
    screen_speed: Optional[Union[int, float]] = None

"Fly" the map to a new location.


  • longitude (Union[int, float]) –

    The longitude of the new viewport.

  • latitude (Union[int, float]) –

    The latitude of the new viewport.

  • zoom (Union[int, float]) –

    The zoom of the new viewport.

  • pitch (Union[int, float], default: 0 ) –

    The pitch of the new viewport. Defaults to 0.

  • bearing (Union[int, float], default: 0 ) –

    The bearing of the new viewport. Defaults to 0.

  • duration (int, default: 4000 ) –

    The number of milliseconds for the viewport transition to take. Defaults to 4000.

  • curve (Optional[Union[int, float]], default: None ) –

    The zooming "curve" that will occur along the flight path. Default 1.414.

  • speed (Optional[Union[int, float]], default: None ) –

    The average speed of the animation defined in relation to curve, it linearly affects the duration, higher speed returns smaller durations and vice versa. Default 1.2.

  • screen_speed (Optional[Union[int, float]], default: None ) –

    The average speed of the animation measured in screenfuls per second. Similar to speed it linearly affects the duration, when specified speed is ignored.

layers class-attribute instance-attribute

layers = tag(sync=True, **widget_serialization)

One or more Layer objects to display on this map.

parameters class-attribute instance-attribute

parameters = tag(sync=True)

GPU parameters to pass to

This is an advanced API. The vast majority of users should not need to touch this setting.


The docstring below is copied from upstream documentation. Any usage of GL refers to the constants defined in here, which comes from the MDN docs here.

In place of any GL constant, you can use the underlying integer it represents. For example, instead of the JS

depthFunc: GL.LEQUAL

referring to the MDN docs, you should use

depthFunc: 0x0203

Note that these parameters do not yet work with integer keys. If you would like to use integer keys, open an issue.

Expects an object with GPU parameters. Before each frame is rendered, this object will be passed to's setParameters function to reset the GPU context parameters, e.g. to disable depth testing, change blending modes etc. The default parameters set by Deck on initialization are the following:

  blend: true,
  polygonOffsetFill: true,
  depthTest: true,
  depthFunc: GL.LEQUAL

Refer to the setParameters API for documentation on supported parameters and values.

import GL from '';
new Deck({
  // ...
  parameters: {
    blendFunc: [GL.ONE, GL.ONE, GL.ONE, GL.ONE],
    depthTest: false


  • Any GPU parameters prop supplied to individual layers will still override the global parameters when that layer is rendered.

picking_radius class-attribute instance-attribute

picking_radius = tag(sync=True)

Extra pixels around the pointer to include while picking (such as for a tooltip).

This is helpful when rendered objects are difficult to target, for example irregularly shaped icons, small moving circles or interaction by touch.

  • Type: int
  • Default: 5


    longitude: Optional[float] = None,
    latitude: Optional[float] = None,
    zoom: Optional[float] = None,
    pitch: Optional[float] = None,
    bearing: Optional[float] = None
) -> None

Set the view state of the map.

Any parameters that are unset will not be changed.

Other Parameters:

  • longitude (Optional[float]) –

    the new longitude to set on the map. Defaults to None.

  • latitude (Optional[float]) –

    the new latitude to set on the map. Defaults to None.

  • zoom (Optional[float]) –

    the new zoom to set on the map. Defaults to None.

  • pitch (Optional[float]) –

    the new pitch to set on the map. Defaults to None.

  • bearing (Optional[float]) –

    the new bearing to set on the map. Defaults to None.

show_tooltip class-attribute instance-attribute

show_tooltip = tag(sync=True)

Whether to render a tooltip on hover on the map.

  • Type: bool
  • Default: True


    filename: Union[str, Path, TextIO, IO[str], None] = None,
    title: Optional[str] = None,
) -> Union[None, str]

Save the current map as a standalone HTML file.


Other Parameters:

  • title (Optional[str]) –

    A title for the exported map. This will show as the browser tab name.


  • Union[None, str]

    If filename is not passed, returns the HTML content as a str.

use_device_pixels class-attribute instance-attribute

use_device_pixels = tag(sync=True)

Controls the resolution of the drawing buffer used for rendering.

Setting this to false or a number <= 1 will improve performance on high resolution displays.

Note: This parameter must be passed to the Map() constructor. It cannot be changed once the map has been created.

The available options are:

  • true: Device (physical) pixels resolution is used for rendering, this resolution is defined by window.devicePixelRatio. On Retina/HD systems this resolution is usually twice as big as CSS pixels resolution.
  • false: CSS pixels resolution (equal to the canvas size) is used for rendering.
  • Number (Experimental): Specified Number is used as a custom ratio (drawing buffer resolution to CSS pixel resolution) to determine drawing buffer size, a value less than one uses resolution smaller than CSS pixels, gives better performance but produces blurry images, a value greater than one uses resolution bigger than CSS pixels resolution (canvas size), produces sharp images but at a lower performance.

  • Type: float, int or bool

  • Default: true

view_state class-attribute instance-attribute

view_state = ViewStateTrait()

The view state of the map.

  • Type: ViewState
  • Default: Automatically inferred from the data passed to the map.

You can initialize the map to a specific view state using this property:

    view_state={"longitude": -74.0060, "latitude": 40.7128, "zoom": 7}


The properties of the view state are immutable. Use set_view_state to modify a map's view state once it's been initially rendered.


Bases: NamedTuple

bearing instance-attribute

bearing: float

Bearing angle in degrees. 0 is north.

latitude instance-attribute

latitude: float

Latitude at the map center.

longitude instance-attribute

longitude: float

Longitude at the map center

pitch instance-attribute

pitch: float

Pitch angle in degrees. 0 is top-down.

zoom instance-attribute

zoom: float

Zoom level.