render_leafmap

render_leafmap class

Reactively render a leafmap map.

render_leafmap(
    _fn: Optional[ValueFn[ValueT]] = None,
    *,
    width: Optional[str] = None,
    height: Optional[str] = None,
    fill: Optional[bool] = None,
    fillable: Optional[bool] = None,
    rate_policy: Optional[RatePolicy] = None,
    rate_delay: Optional[float] = None,
)

@render_leafmap is a decorator that creates a render function – a function that returns the map to display and re-runs when the reactive values it reads change:

import leafmap.leafmap as leafmap

from shinywidgets import render_leafmap


@render_leafmap
def map():
    return leafmap.Map(center=(47.6, -122.3), zoom=10)

leafmap (requires pip install 'shinywidgets[leafmap]') is a high-level API over several mapping engines. Return any of its widget-backed backends:

leafmap.leafmap.Map (the default; an ipyleaflet.Map) – includes leafmap’s toolbar, basemap gallery, legends, and its other tools. This is the backend to start with.
leafmap.maplibregl.Map (a maplibre MapWidget) – vector tiles, globe projection, and deck.gl layers via add_deck_layers().
leafmap.plotlymap.Map (a Plotly FigureWidget) – Plotly map traces and in-place updates through set_center() and update_traces(). Requires Plotly >=5.12 and <7, included in the leafmap extra.
leafmap.kepler.Map (a kepler.gl widget) – kepler.gl’s layer/filter UI, including time playback. Keep in mind that its config trait nests kepler’s own config (e.g., config["config"]["mapState"]).

leafmap’s folium (leafmap.foliumap.Map) and pydeck (leafmap.deck.Map) backends aren’t ipywidgets, so they raise a TypeError that points to alternatives.

Maps fill their container, including in a non-filling page_*(), unless the map has a height of its own (e.g., leafmap.Map(height=400), or Layout(height="300px")). leafmap’s 600px default is treated as unset.

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered widget. Map state can also be read reactively with .read("some_trait") (a shortcut for reactive_read() on .widget). The Plotly backend is already a FigureWidget, so it is rendered directly; .value retains the original map and its leafmap methods.

Responding to user interaction: on the ipyleaflet backend (the default), the map has the same accessors as render_ipyleaflet – bounds(), zoom(), center(), clicked(), and drawn_features(). On the maplibre, plotly, and kepler backends they raise a TypeError; read those backends’ state with .read() instead (e.g., .read("view_state") for the maplibre one). For a trait that shares an accessor’s name (.read() prefers the accessor), use reactive_read() on .widget instead.

Mutating the widget: use .widget to update the rendered map in place (e.g., change its zoom or center, or add layers); trait changes on the widget are synced to the browser.

Typing: .widget is typed as an ipyleaflet.Map (the default backend, and what leafmap.leafmap.Map subclasses), so it type-checks best with that backend. For another backend, .widget is that backend’s widget at runtime.

Parameters

width : Optional[str] = None: A CSS length unit (e.g., "400px" or "100%") for the output’s width.
height : Optional[str] = None: A CSS length unit for the output’s height. When None (the default), the output is designed to fill the height of its parent container (see fill and fillable).
fill : Optional[bool] = None: Whether the output should grow or shrink to fit its parent container. When None (the default), this is True if height is not specified.
fillable : Optional[bool] = None: Whether the output container should fill available space (scrolling its contents on overflow). When None (the default), this is True if height is not specified.
rate_policy : Optional[RatePolicy] = None: How to rate-limit reactive_read() on the widget: "debounce" or "throttle". None (the default) debounces reactive_read() only if rate_delay is given; no accessor on this renderer declares a default.
rate_delay : Optional[float] = None: The rate-limit window in seconds (default 0.25). 0 disables rate limiting.
Each :
which :

render_leafmap class

Note

Parameters

See also