---
title: "Datagrid"
slug: "datagrid"
updated: 2026-01-21T15:05:23Z
published: 2026-01-21T15:05:23Z
canonical: "docs.sightmachine.com/datagrid"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sightmachine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datagrid

BUILD includes a powerful Datagrid visualization type built on top of [MUI DataGrid](https://mui.com/x/react-data-grid/). 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:

```python
# === 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:

```python
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" }
]
```

> [!NOTE]
> 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"`
> 
> ```python
> 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"`).

> [!NOTE]
> All Column Properties
> 
> Full List of column properties can be found [here](https://mui.com/x/api/data-grid/grid-col-def/).
> 
> Note: function properties like: getApplyQuickFilterFn will not work since we are passing JSON from Python to JavaScript.

**Example**

```python
"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](https://momentjs.com/docs/#/displaying/))

```python
{
  "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:

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

Refer to the [MUI DataGrid documentation](https://mui.com/x/api/data-grid/data-grid/#props) 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:

| Property | Description | Example Value |
| --- | --- | --- |
| `cellClassName` | class name applied to every cell | `"small-font font-style-italic"` |
| `headerClassName` | class name applied to the header | `"small-font"` |

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

| Property | Scope | Description | Example |
| --- | --- | --- | --- |
| `headerBgColor` | Header | Background for the column header | `"#FFE0B2"` |
| `headerFontColor` | Header | Text color for the column header | `"#5D3A00"` |
| `columnBgColor` | Cells | Background for all cells in column | `"#FFF7E6"` |
| `columnFontColor` | Cells | Text color for all cells in column | `"#7A4E00"` |

```python
{
  "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:

| Property | Description | Example Value |
| --- | --- | --- |
| `bgColor` | Background color of the row | `"#FFFFFF"` |
| f`ontColor` | Font color of the row | `"#333333"` |

Example:

```python
{
  "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:

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

Example

```python
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
}]
```

![](https://cdn.us.document360.io/c65001f1-30e3-4f1d-b335-57abf64ebd31/Images/Documentation/image(225).png)

#### 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.

> [!NOTE]
> 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:

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

![](https://cdn.us.document360.io/c65001f1-30e3-4f1d-b335-57abf64ebd31/Images/Documentation/image(226).png)

#### 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](https://v7.mui.com/x/api/data-grid/grid-csv-export-options/#properties)

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