Skip to contents

Column Definition

Source: vignettes/column-definition.Rmd
column-definition.Rmd

Column Definition

Column definitions in the Data Grid specify how data is displayed, formatted, and interacted with. Each column has a unique field name and various properties that control its behavior.

Core Properties

field

The unique identifier for the column (required). Must match a field in the row data.

DataGrid() internally handles the mandatory "id" argument required by MUI Data Grid. If the dataset does not contain an "id" column, one is automatically added based on row number using nrow(). If an "id" column already exists in the dataset, it is used as-is.

Warning: If your dataframe already contains an "id" column, each value must be unique — duplicate IDs will cause unexpected behavior in the grid.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name"),
    list(field = "height"),
    list(field = "mass")
  )
)

headerName

The text displayed in the column header. Defaults to the field name if not specified.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", headerName = "Character Name"),
    list(field = "height", headerName = "Height (cm)"),
    list(field = "mass", headerName = "Weight (kg)")
  )
)

description

Tooltip text shown when hovering over the column header.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(
      field = "name",
      headerName = "Name",
      description = "The character's full name"
    ),
    list(
      field = "height",
      headerName = "Height",
      description = "Height in centimeters"
    ),
    list(
      field = "mass",
      headerName = "Mass",
      description = "Weight in kilograms"
    )
  )
)

type

The column type affects formatting and default behavior. Available types: - "string" (default) - "number" - "date" - "dateTime" - "boolean" - "singleSelect"

starwars_typed <- starwars |>
  select(name, height, birth_year) |>
  mutate(is_tall = height > 180) |>
  head()

DataGrid(
  rows = starwars_typed,
  columns = list(
    list(field = "name", type = "string", headerName = "Name", width = 200),
    list(field = "height", type = "number", headerName = "Height", width = 120),
    list(field = "birth_year", type = "number", headerName = "Birth Year", width = 120),
    list(field = "is_tall", type = "boolean", headerName = "Tall?", width = 100)
  )
)

Display Properties

width

Fixed column width in pixels.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", width = 250),
    list(field = "height", width = 120),
    list(field = "mass", width = 120)
  )
)

flex

Flexible column width as a proportion of available space. Cannot be used with width.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", flex = 2),
    list(field = "height", flex = 1),
    list(field = "mass", flex = 1)
  )
)

minWidth / maxWidth

Constraints for column width when using flex or resizing.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", flex = 1, minWidth = 150),
    list(field = "height", flex = 1, minWidth = 80, maxWidth = 120),
    list(field = "mass", flex = 1, minWidth = 80, maxWidth = 120)
  )
)

align / headerAlign

Text alignment for cell content and header.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(
      field = "name", 
      headerAlign = "left", 
      align = "left", 
      width = 200
    ),
    list(
      field = "height", 
      headerAlign = "center", 
      align = "right", 
      width = 120
    ),
    list(
      field = "mass", 
      headerAlign = "center", 
      align = "right", 
      width = 120
    )
  )
)

hide

Hide a column while keeping it in the data.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", width = 200),
    list(field = "height", width = 120),
    list(field = "mass", width = 120, hide = TRUE),
    list(field = "species", width = 150)
  )
)

Interaction Properties

sortable

Enable or disable sorting for the column (default: TRUE).

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", sortable = TRUE, width = 200),
    list(field = "height", sortable = TRUE, width = 120),
    list(field = "mass", sortable = FALSE, width = 120)
  )
)

filterable

Enable or disable filtering for the column (default: TRUE).

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", filterable = TRUE, width = 200),
    list(field = "height", filterable = TRUE, width = 120),
    list(field = "mass", filterable = FALSE, width = 150)
  )
)

editable

Make the column editable (default: FALSE).

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", editable = FALSE, width = 200),
    list(field = "height", editable = TRUE, width = 120),
    list(field = "mass", editable = TRUE, width = 120)
  )
)

resizable

Enable column resizing by dragging borders (default: TRUE).

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", resizable = TRUE, width = 200),
    list(field = "height", resizable = TRUE, width = 120),
    list(field = "mass", resizable = FALSE, width = 120)
  )
)

Value Formatting

valueFormatter

Format the displayed value without changing the underlying data.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", width = 200),
    list(
      field = "height",
      headerName = "Height",
      width = 150,
      valueFormatter = JS("function(value) { return value ? value + ' cm' : 'Unknown'; }")
    ),
    list(
      field = "mass",
      headerName = "Mass",
      width = 150,
      valueFormatter = JS("function(value) { return value ? value + ' kg' : 'Unknown'; }")
    )
  )
)

valueGetter

Compute or derive values from row data.

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name", width = 150),
    list(field = "height", width = 100),
    list(field = "mass", width = 100),
    list(
      field = "bmi",
      headerName = "BMI",
      width = 100,
      type = "number",
      valueGetter = JS("
        function(value, row) {
          if (row.height && row.mass) {
            const heightInM = row.height / 100;
            return Math.round(row.mass / (heightInM * heightInM) * 10) / 10;
          }
          return null;
        }
      ")
    )
  )
)

valueSetter

Control how edited values are stored (for editable columns):

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(field = "name"),
    list(
      field = "height",
      editable = TRUE,
      valueSetter = JS("
        function(value, row) {
          const numValue = Number(value);
          if (!isNaN(numValue) && numValue > 0) {
            row.height = numValue;
            return row;
          }
          return row; // Return unchanged if invalid
        }
      ")
    ),
    list(field = "mass")
  )
)

Advanced Properties

renderCell

Custom cell rendering with React components:

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(
      field = "name",
      renderCell = JS("
        function(params) {
          return React.createElement('strong', {}, params.value);
        }
      ")
    ),
    list(field = "height"),
    list(field = "mass")
  )
)

renderHeader

Custom header rendering:

DataGrid(
  rows = starwars |> select(name, height, mass) |> head(),
  columns = list(
    list(
      field = "name",
      renderHeader = JS("
        function(params) {
          return React.createElement('strong', {}, params.colDef.headerName || params.field);
        }
      ")
    ),
    list(field = "height"),
    list(field = "mass")
  )
)

Column Grouping

Group multiple columns under a common header:

DataGrid(
  rows = starwars |> 
    select(name, height, mass, hair_color, skin_color) |> 
    head(),
  columns = list(
    list(field = "name"),
    list(field = "height"),
    list(field = "mass"),
    list(field = "hair_color"),
    list(field = "skin_color")
  ),
  columnGroupingModel = list(
    list(
      groupId = "physical",
      headerName = "Physical Attributes",
      children = list(
        list(field = "height"),
        list(field = "mass")
      )
    ),
    list(
      groupId = "appearance",
      headerName = "Appearance",
      children = list(
        list(field = "hair_color"),
        list(field = "skin_color")
      )
    )
  )
)

Complete Example

Here’s a comprehensive example using many column properties:

DataGrid(
  rows = starwars |> select(name, height, mass, hair_color, skin_color) |> head(10),
  columns = list(
    list(
      field = "name",
      headerName = "Character Name",
      description = "Name of the Star Wars character",
      width = 180,
      sortable = TRUE,
      filterable = TRUE,
      hideable = FALSE,
      pinnable = TRUE,
      align = "left"
    ),
    list(
      field = "height",
      headerName = "Height",
      description = "Height in centimeters",
      type = "number",
      width = 100,
      align = "center",
      headerAlign = "center",
      valueFormatter = JS("function(value) { return value ? value + ' cm' : 'N/A'; }")
    ),
    list(
      field = "mass",
      headerName = "Mass",
      description = "Mass in kilograms",
      type = "number",
      width = 100,
      align = "center",
      headerAlign = "center",
      valueFormatter = JS("function(value) { return value ? value + ' kg' : 'N/A'; }")
    )
  ),
  initialState = list(
    pagination = list(
      paginationModel = list(pageSize = 5)
    )
  )
)