render_itables

render_itables class

Reactively render a pandas or polars data frame as an interactive itables (DataTables) table.

Usage Source

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

import pandas as pd

from shinywidgets import render_itables

df = pd.DataFrame({"a": [1, 2, 3], "b": ["x", "y", "z"]})


@render_itables
def table():
    return df

The render function may return either a data frame (which is coerced to an itables.widget.ITable) or an itables.widget.ITable widget, which is how to pass itables options such as select=True (requires pip install 'shinywidgets[itables]').

In a filling layout, the table fills its container and scrolls its rows. In a container shorter than roughly 350px the rows get a minimum height of about two rows and the output scrolls, so DataTables’ controls stay reachable; prefer taller containers (or fewer controls, e.g., layout={"topStart": None}) when space is tight. selected_rows holds row positions in the current data frame; ITable.update(df) keeps those positions as-is, and drops options such as columnDefs and buttons unless they are passed again.

Note

Accessing the rendered widget: the render function gains two read-only attributes: .value, the value it most recently returned, and .widget, the rendered ITable instance. Widget state (e.g., selected_rows) can also be read reactively with .read("some_trait") (a shortcut for reactive_read() on .widget).

Responding to user interaction: read the selected rows reactively with .selected().

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

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.

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

selected()

The currently selected rows as a list of positions into the table’s data frame (use df.iloc[table.selected()]), or [] while nothing is selected.

selected()

render_itables.selected()

The currently selected rows as a list of positions into the table’s data frame (use df.iloc[table.selected()]), or [] while nothing is selected.

Positions are in data order, not display order: they survive sorting and searching, and the same position can refer to a different row after .widget.update(df). Requires select=True on the itables.widget.ITable (a plain data frame return has no selection). Not rate-limited.