DataTables has a large number of initialization options, which make it very flexible to customize the table. You can write these options in a list in R, and datatable() will automatically convert them to JSON as needed by DataTables.

1 Default Configurations

The DT package modified the default behavior of DataTables in these aspects:

The table is not ordered by default (DataTables orders a table by its first column by default);
Ordered columns are not highlighted by default (the DataTables option orderClasses is changed from TRUE to FALSE);
Numeric columns are always aligned to the right, since it rarely makes sense for numbers to be aligned to the left;
The option autoWidth is set to FALSE by default, so that DataTables does not calculate and put hard-coded width values on the table columns;
- One known issue with autoWidth = FALSE is that the width option for columns will not work, so if you want to configure widths for columns, you have to use autoWidth = TRUE, e.g.
```
datatable(..., options = list(
  autoWidth = TRUE,
  columnDefs = list(list(width = '200px', targets = c(1, 3)))
))
```
When using the server-side processing mode, the option processing = TRUE is set as the default to show the processing indicator (DataTables’ default is always FALSE);
The option searchDelay is set to 1000 (1 second) by default;

2 Initialization Options

We can pass initialization options to datatable() via the options argument. For example, we center the 5th column in the table below¹, and customize the length menu:

datatable(head(iris, 20), options = list(
  columnDefs = list(list(className = 'dt-center', targets = 5)),
  pageLength = 5,
  lengthMenu = c(5, 10, 15, 20)
))

The target column index is 5 but we actually centered the 6th column: the first column is row names, and the rest of columns are the iris data. The JavaScript index of the 6th column is 5. See the section “Display Row Names” for more details.

# when rownames = FALSE, use 4 as the index of the Species column
datatable(head(iris, 20), rownames = FALSE, options = list(
  columnDefs = list(list(className = 'dt-center', targets = 4)),
  pageLength = 5,
  lengthMenu = c(5, 10, 15, 20)
))

3 Global Options

When there are some options that you want to set for multiple tables produced from the same R session, you can use the global option named DT.options. For example:

options(DT.options = list(pageLength = 5, language = list(search = 'Filter:')))

4 Examples of DataTables Options

4.1 Sorting

We can use the order option to specify how we want to order the rows. For example, we sort the table by columns 2 (ascending) and 4 (descending):

datatable(head(mtcars, 30), options = list(
  order = list(list(2, 'asc'), list(4, 'desc'))
))

4.2 DOM Elements

By default, the table has these DOM elements: the length menu, the search box, the table, the information summary, and the pagination control. You can choose to display a subset of these elements using the dom option. Here are some examples:

# only display the table, and nothing else
datatable(head(iris), options = list(dom = 't'))

# the filtering box and the table
datatable(head(iris), options = list(dom = 'ft'))

4.3 Callbacks in Options

We can also customize the callbacks in DataTables options. For example, we use the initComplete callback function in options to change the background color of the table header to black after the initialization:

datatable(head(iris, 20), options = list(
  initComplete = JS(
    "function(settings, json) {",
    "$(this.api().table().header()).css({'background-color': '#000', 'color': '#fff'});",
    "}")
))

The function JS() tells R that this element is not an ordinary character vector, but literal JavaScript code, which will be evaluated in the web browser. We need this special function because there is no way to encode a JavaScript function in R (using jsonlite) and decode it in the browser.

4.4 Column Rendering

We can define a custom rendering function for particular columns in the option columnDefs. For example, we abbreviate character strings that are wider than 6 characters using the first 6 characters plus an ellipsis (…), and the full character string will be displayed as a tooltip when you mouse over the cell²:

datatable(iris[c(1:20, 51:60, 101:120), ], options = list(columnDefs = list(list(
  targets = 5,
  render = JS(
    "function(data, type, row, meta) {",
    "return type === 'display' && data.length > 6 ?",
    "'<span title=\"' + data + '\">' + data.substr(0, 6) + '...</span>' : data;",
    "}")
))), callback = JS('table.page(3).draw(false);'))

We used the callback argument in datatable() above, to navigate to the 4th page after the table is created. The index 3 in table.page(3) means the 4th page.

4.5 Row Rendering

Similarly, we can define how to render data in the rows using the rowCallback option. In the following example, we display some big numbers, format the 3rd column as currency, and order by this column:

m = as.data.frame(matrix(round(rnorm(100, 1e5, 1e6)), 20))
datatable(m, options = list(
  rowCallback = JS(
    "function(row, data) {",
    "var num = '$' + data[3].toString().replace(/\\B(?=(\\d{3})+(?!\\d))/g, ',');",
    "$('td:eq(3)', row).html(num);",
    "}")
), callback = JS("table.order([3, 'asc']).draw();"))

You need to learn JavaScript regular expressions to understand the above callback function. Basically, it means to add a comma after every 3 decimals, and add a prefix $ to the number. You should know data[2] means the 3rd element in the row now.

Since it is common for users to format numbers in the data columns, we have provided a few simple helper functions (e.g. formatCurrency()) in this package to do these tasks in a much easier way, so you do not have to write the JavaScript code by yourself.

4.6 More Examples

We prepare more examples in this section as users ask questions:

To know more about columnDefs and className, see this reference page.↩︎
See the documentation for columns.render.↩︎