| Title: | High Performance Tables Using 'Cheetah Grid' |
|---|---|
| Description: | An R interface to 'Cheetah Grid', a high-performance JavaScript table widget. 'cheetahR' allows users to render millions of rows in just a few milliseconds, making it an excellent alternative to other R table widgets. The package wraps the 'Cheetah Grid' JavaScript functions and makes them readily available for R users. The underlying grid implementation is based on 'Cheetah Grid' <https://github.com/future-architect/cheetah-grid>. |
| Authors: | Olajoke Oladipo [aut, cre], David Granjon [aut], cynkra GmbH [fnd] |
| Maintainer: | Olajoke Oladipo <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.4.0 |
| Built: | 2026-05-29 19:39:00 UTC |
| Source: | https://github.com/cynkra/cheetahR |
Generates a JS function (wrapped with htmlwidgets::JS) that,
given a record (rec), returns an object with type and message.
add_cell_message(type = c("error", "warning", "info"), message = "message")add_cell_message(type = c("error", "warning", "info"), message = "message")
type |
A string that specifies the type of message.
One of |
message |
A string or JS expression. If it contains |
A htmlwidgets::JS object containing a JavaScript function definition:
function(rec) {
return {
type: "<type>",
message: <message>
};
}
Use this within column_def() for cell validation
set.seed(123) iris_rows <- sample(nrow(iris), 10) data <- iris[iris_rows, ] # Simple warning cheetah( data, columns = list( Species = column_def( message = add_cell_message(type = "info", message = "Ok") ) ) ) # Conditional error using `js_ifelse()` cheetah( data, columns = list( Species = column_def( message = add_cell_message( message = js_ifelse(Species == "setosa", "", "Invalid") ) ) ) ) # Directly using a JS expression as string cheetah( data, columns = list( Sepal.Width = column_def( style = list(textAlign = "left"), message = add_cell_message( type = "warning", message = "rec['Sepal.Width'] <= 3 ? 'NarrowSepal' : 'WideSepal';" ) ) ) )set.seed(123) iris_rows <- sample(nrow(iris), 10) data <- iris[iris_rows, ] # Simple warning cheetah( data, columns = list( Species = column_def( message = add_cell_message(type = "info", message = "Ok") ) ) ) # Conditional error using `js_ifelse()` cheetah( data, columns = list( Species = column_def( message = add_cell_message( message = js_ifelse(Species == "setosa", "", "Invalid") ) ) ) ) # Directly using a JS expression as string cheetah( data, columns = list( Sepal.Width = column_def( style = list(textAlign = "left"), message = add_cell_message( type = "warning", message = "rec['Sepal.Width'] <= 3 ? 'NarrowSepal' : 'WideSepal';" ) ) ) )
Adds a new row to a cheetah grid widget without redrawing the entire widget.
add_row(proxy, data)add_row(proxy, data)
proxy |
A proxy object created by |
data |
A single row dataframe for the new row in the table |
Creates a high-performance table widget using Cheetah Grid.
cheetah( data, columns = NULL, column_group = NULL, width = NULL, height = NULL, elementId = NULL, rownames = TRUE, search = c("disabled", "exact", "contains"), sortable = TRUE, editable = FALSE, disable_column_resize = FALSE, column_freeze = NULL, default_row_height = NULL, default_col_width = NULL, header_row_height = NULL, theme = NULL, font = NULL, underlay_background_color = NULL, allow_range_paste = FALSE, keyboard_options = NULL )cheetah( data, columns = NULL, column_group = NULL, width = NULL, height = NULL, elementId = NULL, rownames = TRUE, search = c("disabled", "exact", "contains"), sortable = TRUE, editable = FALSE, disable_column_resize = FALSE, column_freeze = NULL, default_row_height = NULL, default_col_width = NULL, header_row_height = NULL, theme = NULL, font = NULL, underlay_background_color = NULL, allow_range_paste = FALSE, keyboard_options = NULL )
data |
A data frame or matrix to display |
columns |
A list of column definitions. Each column can be customized using
|
column_group |
A list of column groups. Each group can be customized using |
width |
Width of the widget |
height |
Height of the widget |
elementId |
The element ID for the widget |
rownames |
Logical. Whether to show rownames. Defaults to TRUE. |
search |
Whether to enable a search field on top of the table.
Default to |
sortable |
Logical. Whether to enable sorting on all columns. Defaults to TRUE. |
editable |
Logical. Whether to enable cell editing. Defaults to FALSE. |
disable_column_resize |
Logical. Whether to disable column resizing. Defaults to FALSE. |
column_freeze |
Integer. The number of columns to freeze from the left. |
default_row_height |
Integer. The default row height. |
default_col_width |
Integer. The default column width. |
header_row_height |
Integer. The header row height. |
theme |
The theme to use for the widget. Provide a named list of valid styling options to customize the widget. For possible options, see Extend Theme in Cheetah Grid |
font |
A String. The font to use for the widget. This is possible to set a font value according
to the standard CSS font properties shorthand declaration. For example, |
underlay_background_color |
The underlay background color of the widget. |
allow_range_paste |
Logical. Whether to allow range pasting. Defaults to FALSE.
To activate this option set |
keyboard_options |
A named list of keyboard options. There are four options:
|
An HTML widget object of class 'cheetah' that can be:
Rendered in R Markdown documents
Used in Shiny applications
Displayed in R interactive sessions
The widget renders as an HTML table with all specified customizations.
# Basic usage cheetah(iris) # Customize columns cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ) ) # Customize rownames cheetah( mtcars, columns = list( rownames = column_def(width = 150, style = list(color = "red")) ) ) # Customize column groups cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ), column_group = list( column_group(name = "Sepal", columns = c("Sepal.Length", "Sepal.Width")), column_group(name = "Petal", columns = c("Petal.Length", "Petal.Width")) ) ) # Enable search cheetah(iris, search = "contains") # Enable sorting cheetah(iris, sortable = TRUE) # Enable cell editing cheetah(iris, editable = TRUE) # Disable column resizing cheetah(iris, disable_column_resize = TRUE) # Freeze columns cheetah(iris, column_freeze = 2) # Set default row height cheetah(iris, default_row_height = 30)# Basic usage cheetah(iris) # Customize columns cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ) ) # Customize rownames cheetah( mtcars, columns = list( rownames = column_def(width = 150, style = list(color = "red")) ) ) # Customize column groups cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ), column_group = list( column_group(name = "Sepal", columns = c("Sepal.Length", "Sepal.Width")), column_group(name = "Petal", columns = c("Petal.Length", "Petal.Width")) ) ) # Enable search cheetah(iris, search = "contains") # Enable sorting cheetah(iris, sortable = TRUE) # Enable cell editing cheetah(iris, editable = TRUE) # Disable column resizing cheetah(iris, disable_column_resize = TRUE) # Freeze columns cheetah(iris, column_freeze = 2) # Set default row height cheetah(iris, default_row_height = 30)
Creates a proxy object for a cheetah grid widget that can be used to modify the grid without redrawing the entire widget.
cheetah_proxy(outputId, session = shiny::getDefaultReactiveDomain())cheetah_proxy(outputId, session = shiny::getDefaultReactiveDomain())
outputId |
The id of the cheetah table to create a proxy for. |
session |
The Shiny session object. The default is to get the current session. |
A proxy object that can be used to modify the grid.
Output and render functions for using cheetah within Shiny applications and interactive Rmd documents.
cheetahOutput(outputId, width = "100%", height = "400px") renderCheetah(expr, env = parent.frame(), quoted = FALSE)cheetahOutput(outputId, width = "100%", height = "400px") renderCheetah(expr, env = parent.frame(), quoted = FALSE)
outputId |
output variable to read from |
width, height
|
Must be a valid CSS unit (like |
expr |
An expression that generates a cheetah |
env |
The environment in which to evaluate |
quoted |
Is |
cheetahOutput returns a Shiny output function that can be used in the UI definition.
renderCheetah returns a Shiny render function that can be used in the server definition.
This file contains utility functions for working with cheetahR in Shiny applications.
Needed by cheetah to customize columns individually.
column_def( name = NULL, width = NULL, min_width = NULL, max_width = NULL, column_type = NULL, action = NULL, auto_complete_opts = NULL, menu_options = NULL, style = NULL, message = NULL, sort = FALSE )column_def( name = NULL, width = NULL, min_width = NULL, max_width = NULL, column_type = NULL, action = NULL, auto_complete_opts = NULL, menu_options = NULL, style = NULL, message = NULL, sort = FALSE )
name |
Custom name. |
width |
Column width. |
min_width |
Column minimal width. |
max_width |
Column max width. |
column_type |
Column type. By default, the column type is inferred from the data type of the column. There are 7 possible options:
|
action |
The action property defines column actions. Select the appropriate Action class for the column type.
|
auto_complete_opts |
Character vector of suggestions shown by the
autocomplete dropdown. Required when |
menu_options |
A list of menu options when using |
style |
Column style. |
message |
Cell message. Expect a |
sort |
Whether to sort the column. Default to FALSE. May also be a JS callback to create custom logic (does not work yet). |
When you write a message, you can pass a function like so:
<COLNAME> = column_def(
action = "input",
message = JS(
"function(rec) {
return {
//info message
type: 'info',
message: rec.<COLNAME> ? null : 'Please check.',
}
}")
)
Or use add_cell_message():
<COLNAME> = column_def(
action = "input",
message = add_cell_message(type = "info", message = "Ok")
)
See add_cell_message() for more details.
A list of column options to pass to the JavaScript API.
cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ) ) # Autocomplete editor backed by a fixed list of suggestions cheetah( data.frame(country = c("France", "Germany"), stringsAsFactors = FALSE), editable = TRUE, rownames = FALSE, columns = list( country = column_def( action = "autocomplete", auto_complete_opts = c("France", "Germany", "Ghana", "India") ) ) )cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ) ) # Autocomplete editor backed by a fixed list of suggestions cheetah( data.frame(country = c("France", "Germany"), stringsAsFactors = FALSE), editable = TRUE, rownames = FALSE, columns = list( country = column_def( action = "autocomplete", auto_complete_opts = c("France", "Germany", "Ghana", "India") ) ) )
Creates a column group definition for grouping columns in a Cheetah Grid widget.
column_group(name = NULL, columns, header_style = NULL)column_group(name = NULL, columns, header_style = NULL)
name |
Character string. The name to display for the column group. |
columns |
Character vector. The names of the columns to include in this group. |
header_style |
Named list of possibleCSS style properties to apply to the column group header. |
A list containing the column group definition.
cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ), column_group = list( column_group(name = "Sepal", columns = c("Sepal.Length", "Sepal.Width")), column_group(name = "Petal", columns = c("Petal.Length", "Petal.Width")) ) )cheetah( iris, columns = list( Sepal.Length = column_def(name = "Length"), Sepal.Width = column_def(name = "Width"), Petal.Length = column_def(name = "Length"), Petal.Width = column_def(name = "Width") ), column_group = list( column_group(name = "Sepal", columns = c("Sepal.Length", "Sepal.Width")), column_group(name = "Petal", columns = c("Petal.Length", "Petal.Width")) ) )
Deletes a row from a cheetah grid widget without redrawing the entire widget.
delete_row(proxy, row_index)delete_row(proxy, row_index)
proxy |
A proxy object created by |
row_index |
A numeric value representing the index of the row to delete. |
Retrieves the current data state from a cheetah grid widget and converts it
to a data frame. This function should be called within a reactive context
(e.g., inside observe, observeEvent, reactive, or render* functions).
get_grid_data( id, session = shiny::getDefaultReactiveDomain(), handle_rownames = FALSE )get_grid_data( id, session = shiny::getDefaultReactiveDomain(), handle_rownames = FALSE )
id |
Character. The output ID of the cheetah grid widget. |
session |
The Shiny session object. Defaults to the current session. |
handle_rownames |
Either a logical or a character column name. If
|
The function constructs the input ID by appending _data_state to the
provided grid ID, retrieves the data from the Shiny input, and converts
the nested list structure to a data frame.
A data frame containing the current state of the grid data, or NULL if the data state is not available.
## Not run: # In a Shiny server function: server <- function(input, output, session) { observeEvent(input$grid_data_state, { # Use first column as row names (default) current_data <- get_grid_data("grid") print(current_data) }) # Use a specific column as row names: current_data <- get_grid_data("grid", handle_rownames = "rownames") # Do not convert any column to row names: current_data <- get_grid_data("grid", handle_rownames = FALSE) } ## End(Not run)## Not run: # In a Shiny server function: server <- function(input, output, session) { observeEvent(input$grid_data_state, { # Use first column as row names (default) current_data <- get_grid_data("grid") print(current_data) }) # Use a specific column as row names: current_data <- get_grid_data("grid", handle_rownames = "rownames") # Do not convert any column to row names: current_data <- get_grid_data("grid", handle_rownames = FALSE) } ## End(Not run)
Convert an R logical expression into a JS ternary expression
js_ifelse(condition, if_true = "", if_false = "")js_ifelse(condition, if_true = "", if_false = "")
condition |
An R logical expression (supports %in% / %notin% / grepl() / comparisons / & |) |
if_true |
String to return when the condition is TRUE. Default is an empty string, which interprets as |
if_false |
String to return when the condition is FALSE. Default is an empty string, which interprets as |
A single character string containing a JavaScript ternary expression.
Format numeric and date columns using international formatting standards.
Use number_format() to add data formatting to numeric columns and
date_format() to format date columns according to the Intl.DateTimeFormat API.
number_format( style = c("decimal", "currency", "percent", "unit"), currency = NULL, currency_display = c("symbol", "code", "narrowSymbol", "name"), currency_sign = c("standard", "accounting"), unit = NULL, unit_display = c("short", "narrow", "long"), locales = NULL, locale_options = NULL, digit_options = NULL, other_options = NULL ) date_format( locales = NULL, day = c("numeric", "2-digit"), year = c("numeric", "2-digit"), hour = c("numeric", "2-digit"), minute = c("numeric", "2-digit"), second = c("numeric", "2-digit"), month = c("numeric", "2-digit", "long", "short", "narrow"), weekday = c("long", "short", "narrow"), day_period = c("narrow", "long", "short"), hour12 = FALSE, time_zone = NULL, date_style = c("none", "full", "long", "medium", "short"), time_style = c("none", "full", "long", "medium", "short"), more_date_options = NULL, locales_date_options = NULL )number_format( style = c("decimal", "currency", "percent", "unit"), currency = NULL, currency_display = c("symbol", "code", "narrowSymbol", "name"), currency_sign = c("standard", "accounting"), unit = NULL, unit_display = c("short", "narrow", "long"), locales = NULL, locale_options = NULL, digit_options = NULL, other_options = NULL ) date_format( locales = NULL, day = c("numeric", "2-digit"), year = c("numeric", "2-digit"), hour = c("numeric", "2-digit"), minute = c("numeric", "2-digit"), second = c("numeric", "2-digit"), month = c("numeric", "2-digit", "long", "short", "narrow"), weekday = c("long", "short", "narrow"), day_period = c("narrow", "long", "short"), hour12 = FALSE, time_zone = NULL, date_style = c("none", "full", "long", "medium", "short"), time_style = c("none", "full", "long", "medium", "short"), more_date_options = NULL, locales_date_options = NULL )
style |
The formatting style to use. Must be one of the following:
|
currency |
The ISO 4217 currency code to use for currency formatting. Must be provided if |
currency_display |
The display format for the currency. Must be one of the following:
|
currency_sign |
The sign to use for the currency. Must be one of the following:
|
unit |
The unit to use for the unit formatting. Must be provided if |
unit_display |
The display format for the unit. Must be one of the following:
|
locales |
A character vector of BCP 47 language tags (e.g. |
locale_options |
A named list of options to customize the locale. |
digit_options |
A named list of options to customize the digit. |
other_options |
A named list of other options to customize the number formatting. |
day, month, year, hour, minute, second
|
The format to use for the day, month,
year, hour, minute, and second. The possible values are |
weekday, day_period
|
The format to use for the weekday and day period.
The possible values are |
hour12 |
Whether to use 12-hour time format or the 24-hour format. Default is FALSE. |
time_zone |
The time zone to use for the date formatting. E.g. |
date_style, time_style
|
The format to use for the date and time styles.
The available values are |
more_date_options |
A named list of other options to customize the date formatting. |
locales_date_options |
A named list of options to customize the locales for the date. @note Further details on customizing numeric formatting can be found in the Intl.NumberFormat documentation. Further details on customizing date formatting can be found in the Intl.DateTimeFormat documentation |
For number_format(): A list containing number formatting options that can be used to format numeric data in a column.
For date_format(): A list containing date formatting options that can be used to format date data in a column.
# Number formatting examples data <- data.frame( price_USD = c(125000.75, 299.99, 7890.45), price_EUR = c(410.25, 18750.60, 1589342.80), liter = c(20, 35, 42), percent = c(0.875, 0.642, 0.238) ) cheetah( data, columns = list( price_USD = column_def( name = "USD", column_type = number_format( style = "currency", currency = "USD" ) ), price_EUR = column_def( name = "EUR", column_type = number_format( style = "currency", currency = "EUR", locales = "de-DE" ) ), liter = column_def( name = "Liter", column_type = number_format( style = "unit", unit = "liter", unit_display = "long" ) ), percent = column_def( name = "Percent", column_type = number_format(style = "percent") ) ) ) # Date formatting examples date_data <- data.frame( date = as.Date(c("2024-01-01", "2024-01-02", "2024-01-03")) ) cheetah( date_data, columns = list( date = column_def( name = "Date", column_type = date_format( locales = "en-US", day = "2-digit", month = "long", year = "numeric" ) ) ) )# Number formatting examples data <- data.frame( price_USD = c(125000.75, 299.99, 7890.45), price_EUR = c(410.25, 18750.60, 1589342.80), liter = c(20, 35, 42), percent = c(0.875, 0.642, 0.238) ) cheetah( data, columns = list( price_USD = column_def( name = "USD", column_type = number_format( style = "currency", currency = "USD" ) ), price_EUR = column_def( name = "EUR", column_type = number_format( style = "currency", currency = "EUR", locales = "de-DE" ) ), liter = column_def( name = "Liter", column_type = number_format( style = "unit", unit = "liter", unit_display = "long" ) ), percent = column_def( name = "Percent", column_type = number_format(style = "percent") ) ) ) # Date formatting examples date_data <- data.frame( date = as.Date(c("2024-01-01", "2024-01-02", "2024-01-03")) ) cheetah( date_data, columns = list( date = column_def( name = "Date", column_type = date_format( locales = "en-US", day = "2-digit", month = "long", year = "numeric" ) ) ) )