render_bqplot

render_bqplot class

Reactively render a bqplot figure.

render_bqplot(
    _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_bqplot is a decorator that creates a render function – a function that returns the figure to display and re-runs when the reactive values it reads change:

import bqplot.pyplot as bplt

from shinywidgets import render_bqplot


@render_bqplot
def fig():
    fig = bplt.figure()
    bplt.plot([1, 2, 3], [1, 4, 9])
    return fig

The render function should return a bqplot.Figure, including one created through the bqplot.pyplot interface (requires pip install 'shinywidgets[bqplot]').

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered Figure instance. Widget state can also be read reactively with reactive_read().

Responding to user interaction: read fig.selected() (the selected elements of each mark) or fig.brush() (the current brush region) in a reactive function (a @render.* function, @reactive.calc, or @reactive.effect), which re-runs whenever the user selects or brushes (with a brush/lasso bqplot.interacts.Selector, or by click-select), much like input.my_slider() reads an input. The selections are arrays of row positions, not index labels; fig.selected_rows(df) returns the selected rows of a data frame instead. A re-render (e.g. when the render function reads an input) gives the user a new figure, whose marks start out unselected. They can’t be read inside this output’s own render function, which builds a new figure each time it runs. To react to one mark’s selection specifically, reactive_read(fig.widget.marks[0], "selected") remains available.

Mutating the widget: use .widget to update the rendered figure in place; trait changes on the widget are synced to the browser.

When using bqplot.pyplot, start the render function with fig = bplt.figure(...) and return fig. pyplot’s “current figure” is global to the Python process, so plotting without bplt.figure() (or with bplt.figure(key=...)) reuses one figure across renders, outputs and sessions, which fails after the first re-render.

The figure’s built-in toolbar (display_toolbar=True) and a standalone bqplot.Toolbar work, and the active PanZoom is readable with fig.read("interaction").

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 selected() and brush() (debounced by default) and reactive_read() on the widget: "debounce" or "throttle". None (the default) keeps the debounce, and debounces reactive_read() only if rate_delay is given.
rate_delay : Optional[float] = None: The rate-limit window in seconds (default 0.25). 0 disables rate limiting.
Each :
which :

Methods

`brush()`	The region of the figure’s current brush selector, in data coordinates: a 2x2 `numpy.ndarray` `[[x0, y0], [x1, y1]]` for a `BrushSelector`, a length-2 array for a `BrushIntervalSelector`, or a dict of named intervals for a `MultiSelector` — the selector’s own `selected` trait.
`selected()`	The selected elements of each mark, as a list aligned with `fig.marks`: each entry is a `numpy.ndarray` of element indices, or `None` until that mark has been selected.
`selected_rows()`	The rows of `df` at the selected positions of one mark (see `selected()`).

brush()

render_bqplot.brush()

The region of the figure’s current brush selector, in data coordinates: a 2x2 numpy.ndarray [[x0, y0], [x1, y1]] for a BrushSelector, a length-2 array for a BrushIntervalSelector, or a dict of named intervals for a MultiSelector — the selector’s own selected trait.

None while nothing is brushed, and whenever the figure’s interaction isn’t a brush selector (e.g., PanZoom; LassoSelector has no region trait). Debounced (250 ms) by default; see the rate_policy and rate_delay parameters.

selected()

render_bqplot.selected()

The selected elements of each mark, as a list aligned with fig.marks: each entry is a numpy.ndarray of element indices, or None until that mark has been selected.

Set by a brush/lasso bqplot.interacts.Selector (the figure’s interaction) or by click-select (interactions={"click": "select"}). Single-mark figures read fig.selected()[0]. Debounced (250 ms) by default, since brush selectors update during the drag; see the rate_policy and rate_delay parameters. The indices are positions into the mark’s data: after in-place data replacement through .widget (mark.x = ...), a retained index can point at a different element, so key lookups by ID rather than position when the data can change.

selected_rows()

render_bqplot.selected_rows(
    df: IntoDataFrameT,
    *,
    mark: Optional[Union[int, 'Mark']] = None,
)

The rows of df at the selected positions of one mark (see selected()).

df is required: a bqplot figure retains no data frame. Any frame type works (pandas, polars, …); the result has the same type. mark is the mark whose selection maps to df’s rows – its index in fig.marks, or the Mark object itself – and may be omitted when the figure has exactly one mark. Empty while that mark has nothing selected, so it can be passed straight to @render.data_frame. Cancels until the browser first reports, like selected().

The match is positional (df.iloc[fig.selected()[i]]), so after a re-render or in-place data replacement through .widget (mark.x = ...), a retained position can point at a different row – carry an ID column and look rows up by it when the data can change.

mark resolves against the same report as the selections, which the debounce can leave lagging an in-place change to fig.marks; a mark the report doesn’t know yet cancels until it is reported.