render.DataTable

render.DataTable(
    self
    data
    *
    width='fit-content'
    height='500px'
    summary=True
    filters=False
    editable=False
    selection_mode='none'
    styles=None
    row_selection_mode='deprecated'
)

Holds the data and options for a data_frame output, for a spreadsheet-like view.

This class is used to wrap the returned data frame from a @render.data_frame render function. It allows you to specify options for the data table, such as the width and height of the table, whether to show a summary message, whether to show filter inputs, whether the cells are editable, and how the cells are selected.

While there are currently no execution or parameter differences between DataGrid and DataTable other than CSS styling in the browser, the two classes are kept separate to allow for future extensibility.

Parameters

data : IntoDataFrameT

A pandas, polars, or eager narwhals compatible DataFrame object.

width : str | float | None = 'fit-content'

A maximum amount of vertical space for the data table to occupy, in CSS units (e.g. "400px") or as a number, which will be interpreted as pixels. The default is fit-content, which sets the table’s width according to its contents. Set this to 100% to use the maximum available horizontal space.

height : str | float | None = '500px'

A maximum amount of vertical space for the data table to occupy, in CSS units (e.g. "400px") or as a number, which will be interpreted as pixels. If there are more rows than can fit in this space, the table body will scroll. Set the height to None to allow the table to grow to fit all of the rows (this is not recommended for large data sets, as it may crash the browser).

summary : bool | str = True

If True (the default), shows a message like “Viewing rows 1 through 10 of 20” below the grid when not all of the rows are being shown. If False, the message is not displayed. You can also specify a string template to customize the message, containing {start}, {end}, and {total} tokens. For example: "Viendo filas {start} a {end} de {total}".

filters : bool = False

If True, shows a row of filter inputs below the headers, one for each column.

editable : bool = False

If True, allows the user to edit the cells in the grid. When a cell is edited, the new value is sent to the server for processing. The server can then return a new value for the cell, which will be displayed in the grid.

selection_mode : SelectionModeInput = 'none'

Single string or a set/list/tuple of string values to define possible ways to select data within the data frame. Supported values: * Use "none" to disable any cell selections or editing. * Use "row" to allow a single row to be selected at a time. * Use "rows" to allow multiple rows to be selected by clicking on them individually. Resolution rules: * If "none" is supplied, all other values will be ignored. * If both "row" and "rows" are supplied, "row" will be dropped (supporting "rows").

styles : StyleInfo | list[StyleInfo] | StyleFn[IntoDataFrameT] | None = None

A style info object, a list of style info objects, or a function that receives the (possibly updated) data frame and returns a list of style info objects. The style info objects can be used to apply CSS styles to the data frame. If styles=None, no styling will be applied. Style info object key/value description: * location: This value "body" and is not required. * rows: The row numbers to which the style should be applied. If None, the style will be applied to all rows. * cols: The column numbers to which the style should be applied. If None, the style will be applied to all columns. * style: A dictionary of CSS properties and values to apply to the selected rows and columns. Traditional kebab-cased CSS property names (e.g. background-color) will work in addition to camelCased CSS property names (e.g. backgroundColor). * class: A string of CSS class names to apply to the selected rows and columns. If both style and class are missing or None, nothing will be applied. If both rows and cols are missing or None, the style will be applied to the complete data frame.

row_selection_mode : Literal[‘deprecated’] = 'deprecated'

Deprecated. Please use mode={row_selection_mode}_row instead.

Returns

:

An object suitable for being returned from a @render.data_frame-decorated output function.

See Also

Examples

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
import pandas as pd
import seaborn as sns

from shiny import App, Inputs, Outputs, Session, reactive, render, ui

app_ui = ui.page_fluid(
    ui.head_content(
        ui.tags.meta(name="viewport", content="width=device-width, initial-scale=1")
    ),
    ui.input_select(
        "selection_mode",
        "Selection mode",
        {
            "none": "(None)",
            "row": "Single row",
            "rows": "Multiple rows",
        },
        selected="rows",
    ),
    ui.input_switch("filters", "Filters", True),
    ui.input_switch("editable", "Editable", True),
    ui.layout_column_wrap(
        ui.card(
            ui.card_header("Data Frame as ", ui.tags.code("render.DataGrid")),
            ui.output_data_frame("grid"),
        ),
        ui.card(
            ui.card_header("Data Frame as ", ui.tags.code("render.DataTable")),
            ui.output_data_frame("table"),
        ),
        width=1 / 2,
    ),
    class_="p-3",
)


def server(input: Inputs, output: Outputs, session: Session):
    df: reactive.value[pd.DataFrame] = reactive.value(
        sns.load_dataset("anagrams").iloc[:, 1:]
    )

    def update_data_with_patch(patch):
        df_copy = df().copy()
        fn = str if patch["column_index"] == 0 else int
        df_copy.iat[patch["row_index"], patch["column_index"]] = fn(patch["value"])
        df.set(df_copy)

    height = 350
    width = "fit-content"

    @render.data_frame
    def grid():
        return render.DataGrid(
            df(),
            width=width,
            height=height,
            filters=input.filters(),
            editable=input.editable(),
            selection_mode=input.selection_mode(),
        )

    @grid.set_patch_fn
    def _(*, patch: render.CellPatch):
        update_data_with_patch(patch)
        return patch["value"]

    @render.data_frame
    def table():
        return render.DataTable(
            df(),
            width=width,
            height=height,
            filters=input.filters(),
            editable=input.editable(),
            selection_mode=input.selection_mode(),
        )

    @table.set_patch_fn
    def _(*, patch: render.CellPatch):
        update_data_with_patch(patch)
        return patch["value"]


app = App(app_ui, server)

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
import pandas as pd

from shiny import App, Inputs, render, ui

green_styles = [
    {
        "rows": [2, 4],
        "cols": [2, 4],
        "style": {
            "background-color": "mediumspringgreen",
            "width": "300px",
            "height": "100px",
        },
    }
]

n = 6
df = pd.DataFrame(
    {
        "a": range(n),
        "b": range(n, n * 2),
        "c": range(n * 2, n * 3),
        "d": range(n * 3, n * 4),
        "e": range(n * 4, n * 5),
    }
)

hi_styles = [
    {
        # No `rows` or `cols` means apply to all cells
        "class": "posit-bg",
        "style": {
            "border": "transparent",
            "color": "transparent",
        },
    },
    {
        "rows": [3],
        "cols": [2],
        "class": "posit-blue-bg",
        "style": {
            "width": "100px",
            "height": "75px",
        },
    },
    {
        "cols": [1, 3, 5],
        "class": "posit-blue-bg",
    },
    {
        "cols": [7],
        "rows": [0, 1, 2, 3, 5],
        "class": "posit-orange-bg",
    },
]

n = 7
hi_pd = pd.DataFrame(
    {
        "a": range(n),
        "b": range(n, n * 2),
        "c": range(n * 2, n * 3),
        "d": range(n * 3, n * 4),
        "e": range(n * 4, n * 5),
        "f": range(n * 5, n * 6),
        "g": range(n * 6, n * 7),
        "h": range(n * 7, n * 8),
        "i": range(n * 8, n * 9),
    }
)


app_ui = ui.page_fillable(
    ui.h2("Data Frame with Styles applied to 4 cells"),
    ui.output_data_frame("my_df"),
    ui.hr(),
    ui.tags.style(
        ui.HTML(
            """
        .posit-bg {
            background-color: #242a26 ;
        }
        .posit-blue-bg {
            background-color: #447099 ;
        }
        .posit-orange-bg {
            background-color: #ED642F ;
        }
        """
        )
    ),
    ui.h2(
        "Custom styles applied to all cells within a data frame ", ui.HTML("👋")
    ),
    ui.output_data_frame("hi_df"),
)


def server(input: Inputs):
    @render.data_frame
    def my_df():
        return render.DataGrid(
            df,
            styles=green_styles,
        )

    @render.data_frame
    def hi_df():
        return render.DataGrid(
            hi_pd,
            styles=hi_styles,
        )


app = App(app_ui, server)

Methods

Name Description
to_payload Converts the DataTable object to a payload dictionary.

to_payload

render.DataTable.to_payload()

Converts the DataTable object to a payload dictionary.

Returns

: FrameJson

The payload dictionary representing the DataTable object.