express.render.DataGrid

express.render.DataGrid(
    self
    data
    *
    width='fit-content'
    height=None
    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 grid, such as the width and height of the grid, 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 horizontal space for the data grid 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 grid’s width according to its contents. Set this to 100% to use the maximum available horizontal space.

height : str | float | None = None

A maximum amount of vertical space for the data grid 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 grid will scroll. Set the height to "auto" to allow the grid 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 : RowSelectionModeDeprecated = 'deprecated'

Deprecated. Please use selection_mode= instead.

Returns

:

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

See Also

• output_data_frame - The UI placeholder for a data frame output.
• data_frame - The render method for data frames.
• DataTable - A more tabular view of the data.

Examples

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

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

from shiny import reactive
from shiny.express import input, render, ui

height = 350
width = "fit-content"
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)


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)

with ui.layout_column_wrap(width=1 / 2):
    with ui.card():
        ui.card_header("Data Frame as ", ui.tags.code("render.DataGrid"))

        @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"]

    with ui.card():
        ui.card_header("Data Frame as ", ui.tags.code("render.DataTable"))

        @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"]

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

## file: app.py
import pandas as pd

from shiny.express import 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),
    }
)

ui.h2("Data Frame with Styles applied to 4 cells")


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


ui.hr()

ui.h2("Custom styles applied to all cells within a data frame ", ui.HTML("👋"))

ui.tags.style(
    ui.HTML(
        """
    .posit-bg {
        background-color: #242a26 ;
    }
    .posit-blue-bg {
        background-color: #447099 ;
    }
    .posit-orange-bg {
        background-color: #ED642F ;
    }
    """
    )
)

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),
    }
)


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

Methods

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

to_payload

express.render.DataGrid.to_payload()

Converts the DataGrid object to a payload dictionary.

Returns

: FrameJson

The payload dictionary representing the DataGrid object.