Package 'DT2'

Description

The main function for creating interactive DataTables. Works standalone (R Markdown, Quarto, Viewer) and inside Shiny.

Styling is controlled directly via theme, striped, hover, compact, font_scale – or a CSS class string for full control.

DataTables configuration goes in options (1:1 mapping to the JavaScript API). The two concerns are cleanly separated.

Usage

dt2(
  data,
  theme = "default",
  striped = NULL,
  hover = NULL,
  compact = NULL,
  font_scale = NULL,
  style = NULL,
  class = NULL,
  button_class = NULL,
  responsive = TRUE,
  options = list(),
  extensions = NULL,
  width = "100%",
  height = NULL,
  elementId = NULL
)

Arguments

Value

An htmlwidget object.

Examples

# Just works — beautiful defaults
dt2(iris)


# Override style inline
dt2(iris, striped = FALSE)
dt2(iris, font_scale = 0.85, compact = FALSE)

# Theme presets
dt2(iris, theme = "minimal")
dt2(iris, theme = "compact")

# Reusable theme
my_theme <- dt2_theme("clean", compact = TRUE)
dt2(iris, theme = my_theme)

# Override a preset
dt2(iris, theme = "minimal", striped = TRUE)

# CSS class override (power users)
dt2(iris, class = "table table-bordered table-dark")

# DataTables options (separate from styling)
dt2(iris, options = list(pageLength = 5, searching = FALSE))

# Disable responsive (fixed-width columns)
dt2(iris, responsive = FALSE)

# Everything composes
dt2(mtcars,
    theme = "clean",
    compact = TRUE,
    options = list(pageLength = 25))

# Buttons
dt2(mtcars, options = list(
  buttons = list("copy", "csv", "excel"),
  layout = list(topEnd = "buttons")
))

# Custom button style
dt2(mtcars,
    button_class = "btn btn-sm btn-primary",
    options = list(
      buttons = list("copy", "csv", "excel"),
      layout = list(topEnd = "buttons")
    ))

Description

Bind a DataTables v2 server-side endpoint to a widget id

Usage

dt2_bind_server(
  id,
  data,
  session = shiny::getDefaultReactiveDomain(),
  handler = NULL,
  rows_all = TRUE
)

Arguments

Value

No return value, called for side effects. Registers a Shiny observer on session that responds to client-side server-processing requests for the given widget id.

Description

Configure DataTables Buttons and (optionally) move them to a custom container

Usage

dt2_buttons(
  options = list(),
  buttons = c("copyHtml5", "csvHtml5", "excelHtml5", "pdfHtml5", "print"),
  target = NULL
)

Arguments

Details

Requires the Buttons extension. For CSV/Excel/PDF you also need JSZip and pdfMake (incl. vfs_fonts).

Prefer dt2_use_buttons() for the common case: it takes simple button ids, styles them with a CSS class, and places them in the layout. Use dt2_buttons() when you need full button objects or want to move the rendered buttons into a custom container via target.

Value

The modified options list.

See Also

dt2_use_buttons()

Description

Queries the npm registry to compare installed library versions against the latest available versions. Version constraints are enforced to prevent incompatible major version upgrades (e.g. jQuery 3.x will not jump to 4.x).

Usage

dt2_check_updates(quiet = FALSE)

Arguments

Value

A data.frame (invisibly) with columns: library, installed, latest, latest_ok, constraint, status.

Status values:

"ok"

Library is up to date.

"UPDATE"

A compatible update is available.

"PINNED"

A new major version exists, but is blocked by the version constraint. The library is up to date within its allowed range.

"error"

Lookup failed (check your internet connection).

Examples

dt2_check_updates()

# programmatic use
updates <- dt2_check_updates(quiet = TRUE)
updates[updates$status == "UPDATE", ]

Description

Action button per row

Usage

dt2_col_button(
  options = list(),
  col,
  label = "Action",
  input_id_prefix = "row_btn_"
)

Arguments

Value

Updated options.

Description

Checkbox input per row

Usage

dt2_col_checkbox(
  options = list(),
  col,
  input_id_prefix = "row_chk_",
  value_col = NULL
)

Arguments

Value

Updated options.

Description

Simple HTML template per column (replace {{VAL}})

Usage

dt2_col_template(options = list(), col, template)

Arguments

Value

Updated options.

Description

Column align (Bootstrap 5 classes)

Usage

dt2_cols_align(options = list(), cols, align = c("left", "center", "right"))

Arguments

Value

Updated options.

Description

Controls whether cell content is HTML-escaped before display.

Usage

dt2_cols_escape(options = list(), cols, escape = TRUE)

Arguments

Value

Updated options.

Description

Hide columns

Usage

dt2_cols_hide(options = list(), cols)

Arguments

Value

Updated options.

Description

Mark columns to render raw HTML using a JS render function.

Usage

dt2_cols_html(options = list(), cols, js_render)

Arguments

Value

Updated options.

Description

Provide a custom JS renderer for one or more columns. Use this when you need fine control over columns.render, including returning different outputs based on type (display/sort/filter/type).

Usage

dt2_cols_render_js(options = list(), col_specs, js_render)

Arguments

Value

Modified options.

See Also

https://datatables.net/ref/core/option/columns.render

Description

Supply different renderers for each orthogonal data request. Pass an object with keys display, sort, filter, type (all optional). Each value must be a JS function.

Usage

dt2_cols_render_orthogonal(
  options = list(),
  col_specs,
  display = NULL,
  sort = NULL,
  filter = NULL,
  type = NULL
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = names(iris))
opts <- dt2_cols_render_orthogonal(
  opts, "Sepal.Length",
  display = htmlwidgets::JS("function(d,t,row,meta){ return d + ' cm'; }"),
  sort    = htmlwidgets::JS("function(d,t,row,meta){ return parseFloat(d); }")
)

Description

Column widths (CSS)

Usage

dt2_cols_width(options = list(), map_named)

Arguments

Value

Updated options.

Description

Redraw the table (proxy)

Usage

dt2_draw(proxy)

Arguments

Value

The proxy object, returned invisibly.

Description

List available DataTables extensions

Usage

dt2_extensions()

Value

A data.frame with columns name, version, dir.

Examples

dt2_extensions()

Description

Use DataTables' built-in DataTable.render.datetime to transform date/time strings for display (and preserve sortability).

Usage

dt2_format_datetime(
  options = list(),
  col_specs,
  from = NULL,
  to = "DD/MM/YYYY",
  locale = NULL,
  def = NULL
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = c("when", "val"))
opts <- dt2_format_datetime(opts, "when", from = "YYYY-MM-DD",
                            to = "DD/MM/YYYY", locale = "pt-BR")

Description

Add a number renderer to one or more columns using DataTables' built-in DataTable.render.number.

Usage

dt2_format_number(
  options = list(),
  col_specs,
  thousands = NULL,
  decimal = NULL,
  digits = 0,
  prefix = "",
  prefix_right = ""
)

Arguments

Value

Modified options.

Examples

opts <- list(columns = names(iris))
opts <- dt2_format_number(opts, "Sepal.Length", thousands = ".", decimal = ",",
                          digits = 2, prefix = "", prefix_right = "")

Description

Adds a columns.render function that displays numbers as 1.2k, 3.4M, etc. This renderer lets you control the number of decimal places via digits. Use this when you want a fixed, compact style independent of locale rules.

Usage

dt2_format_number_abbrev(
  options = list(),
  col_specs,
  digits = 1,
  locale = NULL
)

Arguments

Value

The modified options list.

Examples

opts <- list(columns = names(mtcars))
opts <- dt2_format_number_abbrev(opts, c("hp","qsec"), digits = 1, locale = "pt-BR")

Description

Format a date/time using DataTables' datetime renderer, with locale

Usage

dt2_format_time_format(
  options = list(),
  col_specs,
  from = NULL,
  to = "L",
  locale = "pt-br"
)

Arguments

Value

Modified options.

Description

Relative time using moment.fromNow(), with locale

Usage

dt2_format_time_relative(options = list(), col_specs, locale = "pt-br")

Arguments

Value

The modified options list with an updated columnDefs entry.

Description

Language helper (either list or JSON url)

Usage

dt2_language(options = list(), lang_list = NULL, lang_url = NULL)

Arguments

Value

Updated options.

Examples

# Inline translation
opts <- dt2_language(list(), lang_list = list(search = "Buscar:"))
dt2(iris, options = opts)

# Or load a ready-made translation file from the DataTables CDN
opts <- dt2_language(list(),
  lang_url = "https://cdn.datatables.net/plug-ins/2.3.3/i18n/pt-BR.json")

Description

Configures the entries-per-page dropdown.

Usage

dt2_length_menu(options = list(), values = c(10, 25, 50, -1), labels = NULL)

Arguments

Value

Updated options.

Examples

opts <- dt2_length_menu(values = c(5, 10, 25, -1))
dt2(iris, options = opts)

opts <- dt2_length_menu(values = c(10, 50, 100), labels = c("10", "50", "100"))
dt2(iris, options = opts)

Description

Define initial ordering (option order)

Usage

dt2_order(options = list(), ...)

Arguments

Value

Updated options.

Examples

opts <- list(columns = names(mtcars))
opts <- dt2_order(opts, c("mpg", "desc"))
dt2(mtcars, options = opts)

Description

Place a DT2 table in a Shiny UI.

Usage

dt2_output(outputId, width = "100%", height = "auto")

Arguments

Value

An htmlwidgets Shiny output (HTML container) suitable for inclusion in a Shiny UI definition.

Description

Create a proxy for a DT2 table

Usage

dt2_proxy(id, session = shiny::getDefaultReactiveDomain())

Arguments

Value

A "DT2Proxy" object.

Description

Order the table (proxy)

Usage

dt2_proxy_order(proxy, ..., columns = NULL)

Arguments

Value

The proxy object, returned invisibly.

Description

Page navigation (proxy)

Usage

dt2_proxy_page(
  proxy,
  page = c("first", "previous", "next", "last", "number"),
  number = NULL
)

Arguments

Value

The proxy, invisibly.

Description

Global search (proxy)

Usage

dt2_proxy_search(
  proxy,
  value,
  regex = FALSE,
  smart = TRUE,
  caseInsensitive = TRUE
)

Arguments

Value

The proxy, invisibly.

Description

Register a named JS renderer

Usage

dt2_register_renderer(name, js)

Arguments

Value

Invisibly, the name.

Description

Replace all data in the table (proxy)

Usage

dt2_replace_data(proxy, data)

Arguments

Value

The proxy object, returned invisibly.

Description

Set global search (option search)

Usage

dt2_search_global(
  options = list(),
  value,
  regex = FALSE,
  smart = TRUE,
  caseInsensitive = TRUE
)

Arguments

Value

Updated options.

Examples

opts <- dt2_search_global(list(), value = "Toyota")
dt2(mtcars, options = opts)

Description

Select rows (proxy; Select extension)

Usage

dt2_select_rows(proxy, indexes, reset = TRUE)

Arguments

Value

The proxy object, returned invisibly.

Description

Default server-side handler (filter/order/page)

Usage

dt2_ssp_handler(names, rows_all = TRUE)

Arguments

Value

function(data, req) -> list(draw, recordsTotal, recordsFiltered, data, and optionally dt2_rows_all, dt2_rows_current)

Description

Returns a list with reason, order, search, page, selected, rows_all, rows_current, rows_selected and state reflecting the current client-side table state.

Usage

dt2_state(input, id)

Arguments

Details

The widget pushes ⁠input$<id>_state⁠ on every init, draw, order, search, page, select and deselect event. Besides that snapshot, it also sets three standalone inputs with the same names as the DT package, all 1-based row indices into the original data:

• ⁠input$<id>_rows_all⁠ – rows that survive the current filters (global search and per-column searches, e.g. from the ColumnControl extension), in display order.

• ⁠input$<id>_rows_current⁠ – the rows shown on the current page.

• ⁠input$<id>_rows_selected⁠ – the selected rows (Select extension).

The same vectors are available inside the snapshot as rows_all, rows_current and rows_selected. The legacy selected element is kept unchanged (0-based, as DataTables reports it).

With server-side processing the client only holds the current page, so rows_all / rows_current are taken from the server response: the default dt2_ssp_handler() ships them unless rows_all = FALSE (see dt2_bind_server()); a custom handler must return dt2_rows_all / dt2_rows_current itself, otherwise those inputs are NULL. In server mode rows_selected is mapped through rows_current (so it is also NULL without it), and only rows of the current page can be selected, because DataTables discards server-side selections on every redraw. The order, search and page snapshots fire before the server replies, so they carry NULL row vectors; the draw snapshot that follows has the fresh values (the standalone ⁠input$<id>_rows_*⁠ inputs only change on that draw).

Value

A list with the current table state.

Description

Creates a theme object that can be passed to dt2() via the theme parameter. Useful when you want the same look across many tables.

For quick one-off styling, you can also pass arguments directly to dt2() (e.g., dt2(iris, striped = FALSE)).

Usage

dt2_theme(
  preset = "default",
  striped = NULL,
  hover = NULL,
  compact = NULL,
  font_scale = NULL,
  style = NULL,
  button_class = NULL
)

Arguments

Value

A dt2_theme object (a named list).

Examples

# Create and reuse
my_theme <- dt2_theme("clean", compact = TRUE)

dt2(iris, theme = my_theme)
dt2(mtcars, theme = my_theme)


# Custom button style
dt2_theme("default", button_class = "btn btn-sm btn-primary")

# Presets
dt2_theme("minimal")
dt2_theme("compact")

Description

Checks for updates (respecting version constraints), patches version numbers in the source files, and optionally runs tools/get-dt2-libs.sh to download the new files.

Usage

dt2_update_libs(pkg_dir = ".", download = TRUE, dry_run = FALSE)

Arguments

Details

This function only works from the package source tree (i.e. during development). It will refuse to run from an installed package.

The workflow is:

1. Query npm for the latest compatible version of every library.

2. Patch tools/get-dt2-libs.sh (version variables).

3. Patch R/dt2_extensions.R (extension registry).

4. Patch R/dt2_check_updates.R (core lib versions).

5. Patch R/dt2_deps.R (DataTables core version).

6. Run bash tools/get-dt2-libs.sh to download the files.

Version constraints prevent incompatible upgrades:

• jQuery is pinned to 3.x (DataTables 2 requires jQuery 3).

• pdfmake is pinned to 0.2.x (0.3.x has breaking changes and is not available on cdnjs).

• Bootstrap is pinned to 5.x.

Libraries marked as "PINNED" are skipped. Only "UPDATE" items are applied.

Value

Invisibly, a data.frame with the update results.

Examples

## Not run: 
# Developer-only tool: requires the DT2 package source tree
# (DESCRIPTION, tools/get-dt2-libs.sh, R/dt2_extensions.R, ...).
# It cannot run from an installed package, so it is not executable
# in CRAN check or from a regular user session.

# from the DT2 source root:
dt2_update_libs()

# preview changes without modifying anything:
dt2_update_libs(dry_run = TRUE)

## End(Not run)

Description

Uses the modern DataTables 2.x layout API (not the deprecated dom).

Usage

dt2_use_buttons(
  options = list(),
  buttons = c("copy", "csv", "excel", "print"),
  position = "topEnd",
  button_class = NULL
)

Arguments

Value

Updated options.

See Also

dt2_buttons() for a lower-level variant that takes full button objects and can relocate the buttons container to a custom CSS selector.

Examples

opts <- dt2_use_buttons(list(), buttons = c("copy", "csv", "excel"))
dt2(mtcars, options = opts)

Description

Use a named JS renderer on columns

Usage

dt2_use_renderer(options = list(), col_specs, name)

Arguments

Value

Modified options.

Description

Listen for table events (init, draw, order, search, page, select, deselect).

Usage

observe_dt2_events(input, id, handler)

Arguments

Value

No return value, called for side effects. Sets up a Shiny observer that calls handler whenever the table emits an event.

Description

Render a DT2 table in a Shiny server function.

Usage

render_dt2(expr, env = parent.frame(), quoted = FALSE)

Arguments

Value

A Shiny render function (closure produced by htmlwidgets::shinyRenderWidget()) that emits a DT2 widget.