datatable {DT} | R Documentation |
Create an HTML table widget using the DataTables library
Description
This function creates an HTML widget to display rectangular data (a matrix or data frame) using the JavaScript library DataTables.
Usage
datatable(
data,
options = list(),
class = "display",
callback = JS("return table;"),
rownames,
colnames,
container,
caption = NULL,
filter = c("none", "bottom", "top"),
escape = TRUE,
style = "auto",
width = NULL,
height = NULL,
elementId = NULL,
fillContainer = getOption("DT.fillContainer", NULL),
autoHideNavigation = getOption("DT.autoHideNavigation", NULL),
selection = c("multiple", "single", "none"),
extensions = list(),
plugins = NULL,
editable = FALSE
)
Arguments
data |
a data object (either a matrix or a data frame) |
options |
a list of initialization options (see
https://datatables.net/reference/option/); the character options
wrapped in |
class |
the CSS class(es) of the table; see https://datatables.net/manual/styling/classes |
callback |
the body of a JavaScript callback function with the argument
|
rownames |
|
colnames |
if missing, the column names of the data; otherwise it can be
an unnamed character vector of names you want to show in the table header
instead of the default data column names; alternatively, you can provide a
named numeric or character vector of the form |
container |
a sketch of the HTML table to be filled with data cells; by
default, it is generated from |
caption |
the table caption; a character vector or a tag object
generated from |
filter |
whether/where to use column filters; |
escape |
whether to escape HTML entities in the table: |
style |
either |
width , height |
Width/Height in pixels (optional, defaults to automatic sizing) |
elementId |
An id for the widget (a random string by default). |
fillContainer |
|
autoHideNavigation |
|
selection |
the row/column selection mode (single or multiple selection
or disable selection) when a table widget is rendered in a Shiny app;
alternatively, you can use a list of the form |
extensions |
a character vector of the names of the DataTables extensions (https://datatables.net/extensions/index) |
plugins |
a character vector of the names of DataTables plug-ins
(https://rstudio.github.io/DT/plugins.html). Note that only those
plugins supported by the |
editable |
|
Details
selection
:
The argument could be a scalar string, which means the selection
mode
, whose value could be one of'multiple'
(the default),'single'
and'none'
(disable selection).When a list form is provided for this argument, only parts of the "full" list are allowed. The default values for non-matched elements are
list(mode = 'multiple', selected = NULL, target = 'row', selectable = NULL)
.-
target
must be one of'row'
,'column'
,'row+column'
and'cell'
. -
selected
could beNULL
or "indices". -
selectable
could beNULL
,TRUE
,FALSE
or "indices", whereNULL
andTRUE
mean all the table is selectable. WhenFALSE
, it means users can't select the table by the cursor (but they could still be able to select the table viadataTableProxy
, specifyingignore.selectable = TRUE
). If "indices", they must be all positive or non-positive values. All positive "indices" mean only the specified ranges are selectable while all non-positive "indices" mean those ranges are not selectable. The "indices"' format is specified below. The "indices"' format of
selected
andselectable
: whentarget
is'row'
or'column'
, it should be a plain numeric vector; whentarget
is'row+column'
, it should be a list, specifyingrows
andcols
respectively, e.g.,list(rows = 1, cols = 2)
; whentarget
is'cell'
, it should be a 2-colmatrix
, where the two values of each row stand for the row and column index.Note that DT has its own selection implementation and doesn't use the Select extension because the latter doesn't support the server-side processing mode well. Please set this argument to
'none'
if you really want to use the Select extension.
options$columnDefs
:
-
columnDefs
is an option that provided by the DataTables library itself, where the user can set various attributes for columns. It must be provided as a list of list, where each sub-list must contain a vector named 'targets', specifying the applied columns, i.e.,list(list(..., targets = '_all'), list(..., targets = c(1, 2)))
-
columnDefs$targets
is a vector and should be one of:0 or a positive integer: column index counting from the left.
A negative integer: column index counting from the right.
A string: the column name. Note, it must be the names of the original data, not the ones that (could) be changed via param
colnames
.The string "_all": all columns (i.e. assign a default).
When conflicts happen, e.g., a single column is defined for some property twice but with different values, the value that defined earlier takes the priority. For example,
list(list(visible=FALSE, target=1), list(visible=TRUE, target=1))
results in a table whose first column is invisible.See https://datatables.net/reference/option/columnDefs for more.
Note
You are recommended to escape the table content for security reasons (e.g. XSS attacks) when using this function in Shiny or any other dynamic web applications.
References
See https://rstudio.github.io/DT/ for the full documentation.
Examples
library(DT)
# see the package vignette for examples and the link to website
vignette('DT', package = 'DT')
# some boring edge cases for testing purposes
m = matrix(nrow = 0, ncol = 5, dimnames = list(NULL, letters[1:5]))
datatable(m) # zero rows
datatable(as.data.frame(m))
m = matrix(1, dimnames = list(NULL, 'a'))
datatable(m) # one row and one column
datatable(as.data.frame(m))
m = data.frame(a = 1, b = 2, c = 3)
datatable(m)
datatable(as.matrix(m))
# dates
datatable(data.frame(
date = seq(as.Date("2015-01-01"), by = "day", length.out = 5), x = 1:5
))
datatable(data.frame(x = Sys.Date()))
datatable(data.frame(x = Sys.time()))