Title: | High Performance Tables Using 'Cheetah Grid' |
Version: | 0.3.0 |
License: | GPL (≥ 3) |
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. |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.2 |
Depends: | R (≥ 4.1.0) |
Imports: | htmlwidgets, jsonlite, tibble |
Suggests: | testthat (≥ 3.0.0), utils, shiny, quarto, knitr, dplyr, palmerpenguins |
Config/testthat/edition: | 3 |
VignetteBuilder: | quarto |
NeedsCompilation: | no |
Packaged: | 2025-07-17 15:22:27 UTC; olajoke |
Author: | Olajoke Oladipo [aut, cre], David Granjon [aut], cynkra GmbH [fnd] |
Maintainer: | Olajoke Oladipo <olajoke@cynkra.com> |
Repository: | CRAN |
Date/Publication: | 2025-07-21 22:50:07 UTC |
Create a JavaScript cell message function for cheetahR widgets
Description
Generates a JS function (wrapped with htmlwidgets::JS
) that,
given a record (rec
), returns an object with type
and message
.
Usage
add_cell_message(type = c("error", "warning", "info"), message = "message")
Arguments
type |
A string that specifies the type of message.
One of |
message |
A string or JS expression. If it contains |
Value
A htmlwidgets::JS
object containing a JavaScript function definition:
function(rec) { return { type: "<type>", message: <message> }; }
Use this within column_def()
for cell validation
Examples
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';"
)
)
)
)
Add a row to a cheetah table
Description
Adds a new row to a cheetah grid widget without redrawing the entire widget.
Usage
add_row(proxy, data)
Arguments
proxy |
A proxy object created by |
data |
A single row dataframe for the new row in the table |
Create a Cheetah Grid widget
Description
Creates a high-performance table widget using Cheetah Grid.
Usage
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
)
Arguments
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:
|
Value
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.
Examples
# 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)
Shiny bindings for cheetah
Description
Output and render functions for using cheetah within Shiny applications and interactive Rmd documents.
Usage
cheetahOutput(outputId, width = "100%", height = "400px")
renderCheetah(expr, env = parent.frame(), quoted = FALSE)
Arguments
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 |
Value
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.
Cheetah Grid Proxy
Description
Creates a proxy object for a cheetah grid widget that can be used to modify the grid without redrawing the entire widget.
Usage
cheetah_proxy(outputId, session = shiny::getDefaultReactiveDomain())
Arguments
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. |
Value
A proxy object that can be used to modify the grid.
Column definition utility
Description
Needed by cheetah to customize columns individually.
Usage
column_def(
name = NULL,
width = NULL,
min_width = NULL,
max_width = NULL,
column_type = NULL,
action = NULL,
menu_options = NULL,
style = NULL,
message = NULL,
sort = FALSE
)
Arguments
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.
|
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). |
Details
Cell messages
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.
Value
A list of column options to pass to the JavaScript API.
Examples
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 definitions
Description
Creates a column group definition for grouping columns in a Cheetah Grid widget.
Usage
column_group(name = NULL, columns, header_style = NULL)
Arguments
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. |
Value
A list containing the column group definition.
Examples
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"))
)
)
Delete a row from a cheetah grid
Description
Deletes a row from a cheetah grid widget without redrawing the entire widget.
Usage
delete_row(proxy, row_index)
Arguments
proxy |
A proxy object created by |
row_index |
A numeric value representing the index of the row to delete. |
Convert an R logical expression into a JS ternary expression
Description
Convert an R logical expression into a JS ternary expression
Usage
js_ifelse(condition, if_true = "", if_false = "")
Arguments
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 |
Value
A single character string containing a JavaScript ternary expression.
Column formatter
Description
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.
Usage
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
)
Arguments
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 |
Value
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.
Examples
# 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"
)
)
)
)