Package 'muiDataGrid'

Title: 'MUI X Data Grid' for 'shiny' Apps and 'Quarto'
Description: Provides access to 'MUI X Data Grid', a fast and extensible React data table and React data grid, with filtering, sorting, pagination, and more. Bundles the MIT-licensed community edition of the '@mui/x-data-grid' JavaScript library (the commercial 'Pro' and 'Premium' tiers are not included).
Authors: Felix Luginbuhl [aut, cre, cph] (ORCID: <https://orcid.org/0009-0008-6625-2899>), MUI [cph] (Copyright holder of the bundled '@mui/x-data-grid', '@mui/x-virtualizer', '@mui/x-internals', '@mui/private-theming' and '@mui/styled-engine' JavaScript libraries), Meta Platforms, Inc. and affiliates [cph] (Copyright holder of the bundled 'react-is' JavaScript library; 'react' and 'react-dom' are declared as peer dependencies and provided at runtime by 'shiny.react')
Maintainer: Felix Luginbuhl <[email protected]>
License: MIT + file LICENSE
Version: 0.2.0
Built: 2026-10-21 17:57:01 UTC
Source: https://github.com/lgnbhl/muidatagrid

Help Index


DataGrid

Description

DataGrid

Usage

DataGrid(rows = NULL, columns = NULL, ...)

Arguments

rows

A data.frame of rows. An id column of 1-based row numbers is added automatically if not already present.

columns

Column definitions (list of lists, or a data.frame with one row per column). If NULL, auto-generated from names(rows). Any column without an explicit type has one inferred from the matching rows column: numeric columns get MUI's number type and logical columns its boolean type; all other classes (including Date, POSIXct, and factors) default to string. A type you set yourself is always kept. To get MUI's date-picker filtering, set type = "date" together with a valueGetter that returns a JS Date explicitly.

...

Additional props passed directly to the MUI DataGrid component.

Value

A shiny.react element (also classed muiDataGrid) that renders the MUI X Data Grid. Use it directly in Shiny UI, inside renderReact(), or in a Quarto/R Markdown document.

Examples

# Minimal: column definitions are auto-generated from the data frame.
DataGrid(rows = head(iris))

# Custom columns plus an initial page size of 5 rows.
DataGrid(
  rows = head(mtcars),
  columns = list(
    list(field = "mpg", headerName = "MPG"),
    list(field = "cyl", headerName = "Cylinders")
  ),
  initialState = list(
    pagination = list(paginationModel = list(pageSize = 5))
  )
)

Server-Side DataGrid

Description

A DataGrid component with server-side pagination, sorting, and filtering, built on MUI X Data Grid's own server-side data source: whenever the user changes page, sorts, or filters, the grid requests that page from R, and R answers with only those rows.

Usage

DataGridServer(
  inputId,
  rows = NULL,
  columns = NULL,
  rowCount = NULL,
  loading = NULL,
  initialPageSize = NULL,
  pageSizeOptions = NULL,
  filterDebounce = NULL,
  getRows = NULL,
  ...
)

Arguments

inputId

Character. The Shiny input ID. On every data request the grid's state is available as input$<inputId> in the server, a list with elements pagination_model (list with page and pageSize), sort_model (list of sort items), and filter_model (list with items, the filters MUI applies, logicOperator, and — when the toolbar quick filter is used — quickFilterValues). While the quick filter is active the list also holds quick_filter_fields: the columns it searches, each a list with field and type. getRows receives the same list.

rows

A data.frame with the full dataset (like DataGrid()); DataGridServer() pages, sorts, and filters it. Leave NULL when using getRows.

columns

Column definitions (list of lists). If NULL, auto-generated from names(rows), with each column's type inferred from its R class (see DataGrid). Required with getRows.

rowCount

Defunct. Passing it is an error; use getRows instead.

loading

Logical. Usually not needed: the grid shows its loading overlay automatically while it waits for R. TRUE forces it on.

initialPageSize

Integer. Convenience for setting the initial page size. Builds MUI's initialState prop. If NULL, MUI defaults to 100. Must be included in pageSizeOptions. Ignored (with a warning) when you pass your own initialState via ....

pageSizeOptions

Integer vector. Available page size options. If NULL, MUI defaults to c(25, 50, 100).

filterDebounce

Integer. Milliseconds the grid waits after typing in the filter panel before requesting data from R. If NULL, defaults to 300 ms. Superseded by MUI's own filterDebounceMs prop, which you can pass via ... and which takes precedence. The toolbar quick filter has its own debounce.

getRows

A function taking the grid's request (params, the list described under inputId) and returning that page as list(rows = <data.frame>, rowCount = <total number of matching rows>), the shape processGridParams returns. Mirrors MUI's dataSource.getRows. Use it instead of rows to query a database or API page by page.

...

Additional props passed directly to the MUI DataGrid component. Note: MUI's server-side data source forces paginationMode, sortingMode, and filterMode to "server" and pagination to TRUE; passing them only produces a warning.

Details

Pass the full dataset via rows — just like DataGrid() — and DataGridServer() pages, sorts, and filters it in R (see processGridParams). To produce each page yourself (e.g. from a database query), pass getRows: MUI's own data source contract, a function that receives the grid's request and returns that page.

Value

A shiny.react element.

Lifecycle

Experimental. DataGridServer() (together with processGridParams) connects MUI's data source to R and may change in future releases. Pin the package version if you rely on the current behavior. Decisions worth knowing about:

  • Each request is answered over HTTP, through a session-scoped endpoint (session$registerDataObj(), as DT does for server-side tables). Paging therefore does not re-run the renderReact() that created the grid; re-running it (e.g. because rows changed) reloads the current page.

  • getRows is called outside a reactive context, with reactive values isolated. Read the values it depends on (e.g. input$year) in the renderReact() body, so a change re-renders the grid and reloads the page.

  • Changing the sort or any filter resets the grid to the first page.

  • Each DataGridServer() needs its own inputId; two grids sharing one would overwrite each other's state, as with any Shiny input.

  • Unrecognized filter operators pass all rows through with a warning (see processGridParams).

  • When rows have no id column, ids are generated positionally and are not stable across sort/filter changes. Supply a stable, unique id column if you use row selection.

  • initialPageSize, initialState, and any initial sort or filter seed the grid only on the first render. MUI reads them once when the grid mounts, so changing them reactively afterwards (e.g. from a selectInput) has no effect on the already-mounted grid. To change page size after mount, drive it from the grid's own controls rather than re-rendering with a new initialPageSize.

  • A running Shiny session is required: in a static document the grid renders its first page but pagination, sorting, and filtering have nothing to respond to them. Use DataGrid() for static documents.

  • Defunct: passing a pre-sliced page in rows together with rowCount, re-rendered from input$<inputId>, now errors: those rows could belong to another request than the one the grid's footer described. Use getRows instead, e.g. getRows = function(params) processGridParams(data, params).

Examples

## Not run: 
# Pass the full dataset: R pages, sorts, and filters it
output$grid <- renderReact({
  DataGridServer("grid_params",
    rows = my_data,
    initialPageSize = 10L,
    pageSizeOptions = c(10L, 25L, 50L)
  )
})

# Produce each page yourself (e.g. from a database query)
output$grid <- renderReact({
  DataGridServer("grid_params",
    columns = list(list(field = "name"), list(field = "value", type = "number")),
    getRows = function(params) processGridParams(my_data, params),
    initialPageSize = 10L,
    pageSizeOptions = c(10L, 25L, 50L)
  )
})

## End(Not run)

Mui X Data Grid UI JS dependency

Description

Mui X Data Grid UI JS dependency

Usage

muiDataGridDependency()

Value

A list of HTML dependency objects (htmltools::htmlDependency) that load the bundled MUI X Data Grid JavaScript and its shared MUI Material runtime. Attach it to custom HTML when building a grid by hand.

Examples

# Inspect the dependencies attached to every DataGrid() element.
muiDataGridDependency()

Print muiDataGrid components

Description

When called interactively, renders the component in the IDE viewer panel. Otherwise, falls back to standard shiny.tag printing (raw HTML text).

Usage

## S3 method for class 'muiDataGrid'
print(x, browse = interactive(), ...)

Arguments

x

A muiDataGrid object (also inherits shiny.tag).

browse

Whether to render in viewer. Defaults to TRUE in interactive sessions.

...

Additional arguments passed to print.

Value

Invisibly returns x.

Examples

grid <- DataGrid(rows = head(iris))
# browse = FALSE prints the underlying HTML instead of opening the viewer.
print(grid, browse = FALSE)

Process server-side grid parameters

Description

Applies pagination, sorting, and filtering from DataGridServer parameters to a data.frame. Use inside renderReact() with input$<inputId> to get the current page of data.

Usage

processGridParams(data, params, pageSize = 100L)

Arguments

data

A data.frame with all rows.

params

The grid params list from input$<inputId>, or NULL on initial render.

pageSize

Page size to use when params is NULL (i.e. the first render before the grid has sent state). Should match the initialPageSize passed to DataGridServer, or MUI's default of 100 if none was specified.

Value

A list with rows (data.frame for the current page) and rowCount (integer, total matching rows).

Lifecycle

Experimental. This helper is specific to this R package and has no equivalent in MUI X Data Grid, which leaves the server-side data layer entirely to the developer. It reimplements MUI's server-mode filtering and sorting semantics in R, so its behavior may change between releases and can differ in edge cases from MUI's own client-side filtering. Decisions worth knowing about:

  • String filters are case-insensitive (except is, which is case-sensitive); missing values always sort last; unrecognized filter operators pass all rows through with a warning.

  • Filter items with an empty value (NULL, "", or an empty isAnyOf set) are ignored, matching MUI's client-side behavior of disabling such items.

  • The toolbar quick filter is supported: each search term must match at least one searchable column; terms combine per the model's quickFilterLogicOperator ("and" by default), and the result is combined with the regular filter items using AND. As in MUI, number columns match a term equal to their value, other columns match a case-insensitive substring, and boolean columns are not searched. DataGridServer() sends the searchable (visible) columns as quick_filter_fields; without it, every column except id is searched. Values are matched as stored in R, not as formatted by a column's valueFormatter.

  • Sorting and string comparison use R's locale collation, so the ordering of accented or mixed-case values can differ from the browser's ordering in the client-side DataGrid().

  • Date filters compare calendar days. MUI sends a date filter value as a timestamp (e.g. "2024-01-15T00:00:00.000Z"), which is reduced to its date; for dateTime columns the timestamp is in UTC, so a time near midnight can fall on the neighbouring day.

Examples

df <- data.frame(name = paste("Row", 1:50), value = 1:50)

# Initial render (no params yet)
processGridParams(df, params = NULL, pageSize = 10)

# Page 2, sorted descending, filtered
params <- list(
  pagination_model = list(page = 1, pageSize = 10),
  sort_model = list(list(field = "value", sort = "desc")),
  filter_model = list(items = list(
    list(field = "value", operator = ">", value = "10")
  ))
)
processGridParams(df, params)