render_maplibre

render_maplibre class

Reactively render a maplibre map.

Usage Source

render_maplibre(
    _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_maplibre 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:

from maplibre import Map

from shinywidgets import render_maplibre


@render_maplibre
def map():
    return Map()

The render function may return either a maplibre.Map (which is coerced to a maplibre.ipywidget.MapWidget; requires pip install 'shinywidgets[maplibre]') or a maplibre.ipywidget.MapWidget widget. In a filling layout, the map fills its container unless the MapWidget has an explicit height.

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered MapWidget instance.

Responding to user interaction: read map.view_state() (the camera: center, zoom, bounds, bearing, and pitch), map.clicked() (the longitude and latitude of the last click), or map.drawn_features() (the shapes drawn with a MapboxDraw control) in a reactive function (a @render.* function, @reactive.calc, or @reactive.effect), which re-runs whenever the user gestures, much like input.my_slider() reads an input. Feature-level click and hover events aren’t synced. For other traits (e.g. the MapboxDraw draw_features_selected trait), use map.read().

Mutating the widget: to update the rendered map in place, call methods on .widget (e.g., set_paint_property(), set_filter(), set_data(), fit_bounds(), or add_call() for any MapLibre GL JS map method). These are sent to the browser as commands, so assigning traits such as map_options after rendering has no effect.

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 :

See also

output_widget(): in Shiny Core, the UI needs this to hold the output (Shiny Express displays it where the render function is defined).

Methods

clicked()	The most recent map click as {lng, lat}, or None until the first click. Kept across re-renders until the user clicks the new map. MapLibre reports where the click landed, not which feature was hit. Not rate-limited.
drawn_features()	The shapes drawn with the map’s MapboxDraw control, as a list of GeoJSON Feature dicts – [] until something is drawn, updated on every draw create/update/delete. Drawn shapes live on the map, so a re-render starts from the new map’s own (empty) set. Not rate-limited.
view_state()	The map’s current view state: a dict with center ({lng, lat}), zoom, bounds ({_sw, _ne}, MapLibre GL JS’s own field naming), bearing, and pitch.

clicked()

render_maplibre.clicked()

The most recent map click as {lng, lat}, or None until the first click. Kept across re-renders until the user clicks the new map. MapLibre reports where the click landed, not which feature was hit. Not rate-limited.

drawn_features()

render_maplibre.drawn_features()

The shapes drawn with the map’s MapboxDraw control, as a list of GeoJSON Feature dicts – [] until something is drawn, updated on every draw create/update/delete. Drawn shapes live on the map, so a re-render starts from the new map’s own (empty) set. Not rate-limited.

view_state()

render_maplibre.view_state()

The map’s current view state: a dict with center ({lng, lat}), zoom, bounds ({_sw, _ne}, MapLibre GL JS’s own field naming), bearing, and pitch.

The browser reports when a pan or zoom finishes (on the map’s load, zoomend, and moveend events), not per animation frame, so this accessor isn’t rate-limited. Readers cancel (req(False)) until the browser’s first report. A re-render keeps the old value until the new map’s browser reports, then re-seeds from the new map.