Map

deckgl_marimo.Map

Bases: AnyWidget

Interactive map widget with deck.gl layers on a MapLibre GL basemap.

This is the single anywidget that renders all layers. Layers are plain Python objects (subclasses of :class:BaseLayer) that get serialized to JSON specs for the JavaScript frontend.

Parameters:

Name	Type	Description	Default
layers	list[BaseLayer] | None	List of :class:BaseLayer instances to render.	None
basemap	str | dict[str, Any] | MapLibreConfig	Basemap style. Accepts a :class:Basemaps alias like "dark-matter", a full MapLibre style URL, an inline MapLibre style spec dict, or a :class:~deckgl_marimo.maplibre.MapLibreConfig composing a base style with extra sources (WMS/XYZ/vector/GeoJSON) and MapLibre layers.	'dark-matter'
center	tuple[float, float] | None	Initial map center as (longitude, latitude).	None
zoom	float	Initial zoom level (0-22).	1.0
pitch	float	Initial pitch/tilt angle in degrees (0-85).	0.0
bearing	float	Initial rotation angle in degrees.	0.0
height	str	CSS height of the map container.	'600px'
width	str	CSS width of the map container.	'100%'
show_perf_metrics	bool	Enable the FPS/frame-time tracker, which pushes perf_metrics updates every 500 ms while the widget is displayed. Off by default to avoid constant traitlet traffic; can be toggled at runtime (m.show_perf_metrics = True).	False

Examples:

>>> import deckgl_marimo as dgl
>>> m = dgl.Map(
...     layers=[dgl.ScatterplotLayer(data=df, get_position=["lon", "lat"])],
...     basemap="dark-matter",
...     center=(-122.4, 37.8),
...     zoom=10,
... )

layers property

layers

Return the current list of layers.

set_layers

set_layers(layers)

Replace all layers on the map.

This is the recommended way to update layers reactively (e.g. in a marimo cell that depends on slider values): it re-serializes the layer specs and re-packs binary buffers in one call, unlike assigning layer_specs directly, which silently skips binary packing.

Parameters:

Name	Type	Description	Default
layers	list[BaseLayer]	The new list of :class:BaseLayer instances. Replaces any existing layers.	required

add_layer

add_layer(layer)

Add a layer to the map.

Parameters:

Name	Type	Description	Default
layer	BaseLayer	A :class:BaseLayer subclass instance.	required

remove_layer

remove_layer(layer_id)

Remove a layer by its ID.

Parameters:

Name	Type	Description	Default
layer_id	str	The id of the layer to remove.	required

update_layer

update_layer(layer_id, **props)

Update properties of an existing layer.

Parameters:

Name	Type	Description	Default
layer_id	str	The id of the layer to update.	required
**props	Any	Properties to update (snake_case). Validated against the layer's declared props; unknown keys raise TypeError with a "did you mean" suggestion.	{}

fit_bounds

fit_bounds(bounds, *, padding=20)

Fit the viewport to the given bounds.

The JS side applies an exact map.fitBounds(bounds, {padding}). The Python-side view traitlets are also set to the bounds center and an approximate zoom so state is sane before/without a rendered frontend.

Use :func:deckgl_marimo.compute_bounds to derive bounds from layer data.

Parameters:

Name	Type	Description	Default
bounds	list[list[float]]	[[west, south], [east, north]] in degrees.	required
padding	int	Pixel padding around the bounds (applied by the JS side).	20

as_widget

as_widget()

Wrap this Map in marimo.ui.anywidget for reactive .value access.

Equivalent to marimo.ui.anywidget(map); provided so users do not need to import marimo themselves at the call site. marimo is imported lazily, so this method only works inside a marimo-equipped environment — Jupyter / plain-Python users keep using the Map widget directly.

deckgl_marimo.Basemaps

Catalog of free basemap styles for MapLibre GL.

Use class attributes for direct access, or use :meth:resolve to look up by alias.

Examples:

>>> Basemaps.resolve("dark-matter")
'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json'
>>> Basemaps.resolve("https://my-tiles.example.com/style.json")
'https://my-tiles.example.com/style.json'

resolve classmethod

resolve(name_or_url)

Resolve a basemap alias to a style URL.

If the input matches a known alias, returns the corresponding URL. Otherwise, returns the input as-is (assumed to be a direct URL).

list_available classmethod

list_available()

Return a list of available basemap alias names.