Datagrid

BUILD includes a powerful Datagrid visualization type built on top of MUI DataGrid. This component enables fast, customizable data tables with support for advanced styling, custom column types, conditional formatting, and even click-through navigation to other dashboards.

Overview

At a high level the Datagrid "viz_type" is "mui-datagrid" and its config goes under viz_props.tableData. This object should include:

1. "rows"

2. "columns"

3. "dataGridProps" (optional)

4. "cellStyleClassNameMap" (optional)

5. "cellColorMap" (optional)

6. "additionalSettings" (optional)

Here's an example of a table panel:

# === Table UI Panel ===
# Create the Table UI Panel from the SQL/DataFrame output
# ======================

rows = df.to_dict('records')
max_output = df['Output'].max()
highlightRowIds = []
# add a id:<UUID> field to each row (required for mui-datagrid)
for row in rows:
    row["id"] = str(uuid.uuid4())

    # Determine whether to highlight this row
    highlight = (
        max_output is not None
        and isinstance(row.get("Output"), (int, float))
        and float(row["Output"]) == max_output
    )

    # Apply colors (match your app's expected keys)
    if highlight:
        row["bgColor"] = "#B1CE48"   # light green background
        row["fontColor"] = "#008A55" # dark green text
        highlightRowIds.append(row["id"])
    else:
        row["bgColor"] = "#FFFFFF"   # default white
        row["fontColor"] = "#333333" # default dark text

machine_cell_classes = {
    rid: ["text-transform-uppercase", "font-weight-bold"]
    for rid in highlightRowIds
}
# after building highlightRowIds
cellColorMap = {
    "Shift": {
        rid: { "bgColor": "#FF0000", "fontColor": "#0000FF" }
        for rid in highlightRowIds
    }
}

main_table_panel = {
    "id": "main-table",
    "viz_type": "mui-datagrid",
    "viz_props": {
        "tableData": [
            {
                "dataGridProps": {
                    "disableDefaultFlex": True
                },
                "rows": rows,
                "columns": [
                    { "field": "Machine", "type": "string", "headerName": "Machine", "width": 180,
                      "columnBgColor": "#F3F6FF", "columnFontColor": "#1A237E",
                      "headerBgColor": "#E8EAF6", "headerFontColor": "#1A237E",
                      "cellClassName": "normal-font" },
                    { "field": "Shift", "type": "string", "headerName": "Shift", "width": 140,
                      "headerBgColor": "#FAFAFA", "headerFontColor": "#424242",
                      "cellClassName": "small-font" },
                    { "field": "Output", "type": "number", "headerName": "Output", "width": 110,
                      "columnBgColor": "#FFF7E6", "columnFontColor": "#7A4E00",
                      "headerBgColor": "#FFE0B2", "headerFontColor": "#5D3A00",
                      "cellClassName": "font-weight-bolder" }
                ],
                "cellStyleClassNameMap": {
                    "Machine": machine_cell_classes
                },
                "cellColorMap": cellColorMap
            },
        ]
    },
    "title": {
        "value": "Output By Shift Table",
        "font-size": 16,
        "align": "left",
        "margin": "13px 13px 13px 13px"
    },
}

Rows

The Datagrid "rows" should be a list of objects, each representing a row. The keys of the items correspond to the "field" of the columns.

For example:

rows = [
  { "id": 1, "Shift": "Morning", "Output": 120, "Machine": "A1" },
  { "id": 2, "Shift": "Afternoon", "Output": 150, "Machine": "B2" },
  { "id": 3, "Shift": "Evening", "Output": 100, "Machine": "C3" },
  { "id": 4, "Shift": "Night", "Output": 90, "Machine": "D4" },
  { "id": 5, "Shift": "Morning", "Output": 110, "Machine": "E5" }
]

df.to_dict('records')

With DataFrame, the rows can be formatted as follows: This assumes the columns in the data frame matches the columns declared in "columns"

rows = df.to_dict('records')

# add an id:<UUID> field to each row (required for mui-datagrid)
for row in rows
    row["id"] = str(uuid.uuid4())

Columns

Each column must include:

Column Properties

Each column in the Datagrid requires the following properties:

• field: The key in each row that corresponds to the column's data.

• headerName: The label displayed in the column header.

• type: Defines the rendering behavior of the column. Example types include:

  • "string": Displays text.

  • "number": Displays numeric values.

  • Custom types such as "custom-link" or "custom_timezone_date" for specialized rendering.

• width: (Optional) Hardcode the width of the column (e.g., 150).

• columnBgColor: (Optional) Set the background color of the column (e.g., "#FFF7E6").

• columnFontColor: (Optional) Set the font color of the column (e.g., "#7A4E00").

• headerBgColor: (Optional) Set the background color of the column header (e.g., "#E8EAF6").

• headerFontColor: (Optional) Set the font color of the column header (e.g., "#1A237E").

• headerClassName: (Optional) Set the CSS class of the header cell (e.g., "normal-font").

• cellClassName: (Optional) Set the CSS class of the cell (e.g., "normal-font").

All Column Properties

Full List of column properties can be found here.

Note: function properties like: getApplyQuickFilterFn will not work since we are passing JSON from Python to JavaScript.

Example

"columns": [
    { "field": "Machine", "type": "string", "headerName": "Machine", "width": 180,
      "columnBgColor": "#F3F6FF", "columnFontColor": "#1A237E",
      "headerBgColor": "#E8EAF6", "headerFontColor": "#1A237E",
      "cellClassName": "normal-font" },
    { "field": "Shift", "type": "string", "headerName": "Shift", "width": 140,
      "headerBgColor": "#FAFAFA", "headerFontColor": "#424242",
      "cellClassName": "small-font" },
    { "field": "Output", "type": "number", "headerName": "Output", "width": 110,
      "columnBgColor": "#FFF7E6", "columnFontColor": "#7A4E00",
      "headerBgColor": "#FFE0B2", "headerFontColor": "#5D3A00",
      "cellClassName": "font-weight-bolder" }
],

Custom Column Types

BUILD includes two additional column types:

1. custom-link: Renders the cell as a blue clickable link. (Use in conjunction with page-linking).

2. custom_timezone_date: Formats timestamps to the specified timezone (requires time_zone and optional date_format)

{
  "field": "Begin Time",
  "type": "custom_timezone_date",
  "headerName": "Begin Time",
  "time_zone": "America/Los_Angeles",
  "date_format": "YYYY-MM-DD HH:mm:ss"
}

dataGridProps

These are passed directly to the MUI DataGrid. For example:

"dataGridProps": {
  "hideFooter": True,
  "disableDefaultFlex": True
}

Refer to the MUI DataGrid documentation for the full list of props.

Disabling Column Flex

By default, each column has flex: 1. To disable:

• Set disableDefaultFlex: True in dataGridProps, or

• Specify width for individual columns.

Styling Options

Customizable Styles for Data Grids

• Set background and font colors at the column, row, or cell level

• Apply text styles including font size, weight, style, text transform, and decoration

Available Classes:

• Font Weight: .font-weight-bold, .font-weight-normal, .font-weight-bolder

• Font Style: .font-style-italic, .font-style-normal

• Text Transform: .text-transform-uppercase, .lowercase, .capitalize

• Text Decoration: .text-decoration-underline, .line-through

Available font-size class:

• small-font (11px)

• normal-font (13px)

• large-font (15px)

Column Styling

Use cellClassName and headerClassName to style the headers and cells for a column with pre-defined class names:

You can color-code entire columns and/or column headers:

{
  "field": "Shift",
  "type": "string",
  "headerName": "Shift",
  "cellClassName": "small-font",
  "headerClassName": "small-font",
  "headerBgColor": "#FFE0B2",
  "columnBgColor": "#FFF7E6",
  "headerFontColor": "#5D3A00",
  "columnFontColor": "#7A4E00",
}

Row Styling

Use rowClassNames to apply text styling to an entire row: You can define background and font colors for rows using the following properties:

Example:

{
  "Shift": "Crew B",
  "Output": 719,
  "bgColor": "#FFFFFF",
  "fontColor": "#333333",
  "rowClassNames": [
    "font-weight-bold",
    "font-style-italic",
    "text-transform-uppercase"
  ]
}

Cell Styling

Use cellStyleClassNameMap and cellColorMap to apply styles to specific cells. The format is as follows:

"tableData": [{
  "rows": [...],
  "columns": [...]
  "cellStyleClassNameMap": {
    [column]: {
      [row_id] : [classnames]
    }
  }
  "cellColorMap": {
    [column]: {
      [row_id] : { "bgColor": "#HEX", "fontColor": "#HEX" }
    }
  },
  ...
}]

Example

highlight_row_ids = ["d1fb31f2-id"]  # computed in your Python
cellColorMap = {
  "Shift": {
    rid: { "bgColor": "#FF0000", "fontColor": "#0000FF" }
    for rid in highlight_row_ids
  }
}

"tableData": [{
  ...
  "cellStyleClassNameMap": {
    "Shift": {
      "d1fb31f2-id": ["font-weight-bold", "text-transform-uppercase"]
    }
  },
  "cellColorMap": cellColorMap
}]

Precedence Rule

Final precedence: Column < Row < Cell

Row colors override column colors for that row. Cell overrides (below) win over both. Per-cell color (via cellColorMap or classes in cellStyleClassNameMap) is highest priority.

Tip:

We avoid adding row color classes when a row uses the defaults #FFFFFF (bg) and #333333 (font), so default-looking rows keep any column colors you set.

This precedence lets you set broad defaults at the column level, highlight entire rows when needed, and finally accent or call out individual cells with precise control.

Export / Download

Enable CSV download by adding the following to the top level:

"tableData": [{
    "additionalSettings": {
        "showExport": True
    }
}]

Custom Filename

To specify the csv download's filename you can pass in csvOptions in additionalSettings. The example below will create filename: "custom-filename.csv" when exporting the table. Other properties for csvOptions can be found here: https://v7.mui.com/x/api/data-grid/grid-csv-export-options/#properties

"viz_props": {
    "tableData": [
        {
            "dataGridProps": {
                "disableDefaultFlex": True
            },
            "additionalSettings": {
                "showExport": True,
                "csvOptions": {
                    "fileName": "custom-filename",
                    "fields": ["Machine", "Shift"]
                }
            },
            "rows": rows,
            "columns": columns
        },
    ]
}