Draw a Tiny Table — tt • tinytable

The tt function renders a table in different formats with various styling options: HTML, Markdown, LaTeX, Word, PDF, PNG, or Typst. The table can be customized with additional functions:

style_tt(): style fonts, colors, alignment, etc.
format_tt(): format numbers, dates, strings, etc.
group_tt(): row or column group labels.
save_tt(): save the table to a file or return the table as a string.
print(): print to a specific format, ex: print(x, "latex")
theme_*() functions apply a collection of format-specific or visual transformations to a tinytable.

tinytable attempts to determine the appropriate way to print the table based on interactive use, RStudio availability, and output format in RMarkdown or Quarto documents. Users can call print(x, output="markdown") to print the table in a specific format. Alternatively, they can set a global option: options("tinytable_print_output"="markdown")

Usage

tt(x, ...)

# Default S3 method
tt(
  x,
  digits = get_option("tinytable_tt_digits", default = NULL),
  caption = get_option("tinytable_tt_caption", default = NULL),
  notes = get_option("tinytable_tt_notes", default = NULL),
  width = get_option("tinytable_tt_width", default = NULL),
  height = get_option("tinytable_tt_height", default = NULL),
  theme = get_option("tinytable_tt_theme", default = "default"),
  colnames = get_option("tinytable_tt_colnames", default = TRUE),
  rownames = get_option("tinytable_tt_rownames", default = FALSE),
  escape = get_option("tinytable_tt_escape", default = FALSE),
  ...
)

Arguments

x

A data frame, data table, or tibble to be rendered as a table.

...

Additional arguments are ignored

digits

Number of significant digits to keep for numeric variables. When digits is an integer, tt() calls format_tt(x, digits = digits) before proceeding to draw the table. Note that this will apply all default argument values of format_tt(), such as replacing NA by "". Users who need more control can use the format_tt() function instead.

caption

A string that will be used as the caption of the table. This argument should not be used in Quarto or Rmarkdown documents. In that context, please use the appropriate chunk options.

notes

Notes to append to the bottom of the table. This argument accepts several different inputs:

Single string insert a single note: "blah blah"
Multiple strings insert multiple notes sequentially: list("Hello world", "Foo bar")
A named list inserts a list with the name as superscript: list("a" = list("Hello World"))
A named list with positions inserts markers as superscripts inside table cells: list("a" = list(i = 0:1, j = 2, text = "Hello World"))

width

Table or column width.

Single numeric value smaller than or equal to 1 determines the full table width, in proportion of line width.
Numeric vector of length equal to the number of columns in x determines the width of each column, in proportion of line width. If the sum of width exceeds 1, each element is divided by sum(width). This makes the table full-width with relative column sizes.

height

Row height in em units. Single numeric value greater than zero that determines the row height spacing.

theme

Function or string.

String: grid, revealjs, rotate, striped, empty
Function: Applied to the tinytable object.

colnames

TRUE, FALSE, or "label". If "label", use the attr(x$col,"label") attribute if available and fall back on column names otherwise.

rownames

Logical. If TRUE, rownames are included as the first column

escape

Logical. If TRUE, escape special characters in the table. Equivalent to format_tt(tt(x), escape = TRUE).

Value

An object of class tt representing the table.

The table object has S4 slots which hold information about the structure of the table. For example, the table@group_index_i slot includes the row indices for grouping labels added by group_tt().

Warning: Relying on or modifying the contents of these slots is strongly discouraged. Their names and contents could change at any time, and the tinytable developers do not consider changes to the internal structure of the output object to be a "breaking change" for versioning or changelog purposes.

Dependencies

.pdf output requires a full LaTeX installation on the local computer.
.png output requires the webshot2 package.
.html self-contained files require the base64enc package.

LaTeX preamble

tinytable uses the tabularray package from your LaTeX distribution to draw tables. tabularray, in turn, uses the special tblr, talltblr, and longtblr environments.

When rendering a document from Quarto or Rmarkdown directly to PDF, tinytable will populate the LaTeX preamble automatically with all the required packages. For standalone LaTeX documents, these commands should be inserted in the preamble manually:

Note: Your document will fail to compile to PDF in Quarto if you enable caching and you use tinytable due to missing LaTeX headers. To avoid this problem, set the option #| cache: false for the chunk(s) where you use tinytable.

\usepackage{tabularray}
\usepackage{float}
\usepackage{graphicx}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\UseTblrLibrary{siunitx}
\newcommand{\tinytableTabularrayUnderline}[1]{\underline{#1}}
\newcommand{\tinytableTabularrayStrikeout}[1]{\sout{#1}}
\NewTableCommand{\tinytableDefineColor}[3]{\definecolor{#1}{#2}{#3}}

Markdown limitations

Markdown is a text-only format that only supports these styles: italic, bold, strikeout. The width argument is also unavailable. These limitations exist because there is no standard markdown syntax for the other styling options.

However, in terminals (consoles) that support it, tinytable can display colors and text styles using ANSI escape codes by setting theme_markdown(ansi = TRUE). This allows for rich formatting in compatible terminal environments.

Word limitations

Word tables only support these styles: italic, bold, strikeout. The width argument is also unavailable. Moreover, the style_tt() function cannot be used to style headers inserted by the group_tt() function; instead, you should style the headers directly in the header definition using markdown syntax: group_tt(i = list("*italic header*" = 2)). These limitations are due to the fact that we create Word documents by converting a markdown table to .docx via the Pandoc software, which requires going through a text-only intermediate format.

Tabulator (interactive tables)

Experimental Feature: The Tabulator.js integration is experimental and the API may change in future versions.

The Tabulator.js library provides powerful interactive table features including sorting, filtering, pagination, data export, and real-time editing capabilities. This theme customizes the appearance and behavior of Tabulator tables.

Features:

Sorting and filtering of all columns
Pagination with configurable page sizes
Search functionality across all columns
Multiple CSS themes and custom styling
Real-time data export options
Accessibility features (ARIA compliant)

Limitations:

style_tt() supports most styling options (bold, italic, color, background, fontsize, etc.) with cell-level precision. Styles persist across sorting and pagination. Column-wide alignment only (row-specific align/alignv with i argument not supported)
Row-based formatting (format_tt() with i argument) not supported
Global stylesheets affect all tables in multi-table documents
Date formatting uses Luxon tokens, not R's strptime format
Boolean formatting requires format_tt() with bool argument for custom display

Global options

Options can be set with options() and change the default behavior of tinytable. For example:

options(tinytable_tt_digits = 4)
tt(head(iris))

You can set options in a script or via .Rprofile. Note: be cautious with .Rprofile settings as they may affect reproducibility.

Default values for function arguments

Nearly all of the package's functions retrieve their default values from global options. This allows you to set defaults once and apply them to all tables without needing to specify them each time. For example, to fix the the digits argument of the tt() function globally, call:

options(tinytable_tt_digits = 4)

In addition, some more specific options are available to control the behavior of the package in specific contexts.

tinytable_html_mathjax: Insert MathJax scripts (warning: may conflict if MathJax is loaded elsewhere)
tinytable_pdf_clean: Delete temporary and log files for pdf output in save_tt()
tinytable_color_name_normalization: Enable/disable automatic color name processing (default: TRUE). When enabled, R color names recognized by col2rgb() are converted to hex format for consistent rendering across HTML, LaTeX, and Typst formats. If R color conversion fails, LaTeX color names are used as fallback. Colors explicitly supplied as hex values with "#" prefix are passed through unchanged. Set to FALSE to disable processing and pass color names unchanged.

Quarto

The format_tt(quarto=TRUE) argument enables Quarto data processing with some limitations:

The \QuartoMarkdownBase64{} LaTeX macro may not process references and markdown as expected
Quarto processing may conflict with tinytable styling/formatting

Options:

tinytable_quarto_disable_processing: Disable Quarto cell processing

Example of Quarto-specific code in cells:

x <- data.frame(Math = "x^2^", Citation = "@Lovelace1842")
fn <- function(z) sprintf("<span data-qmd='%s'></span>", z)
tt(x) |> format_tt(i = 1, fn = fn)

For more details on Quarto table processing: https://quarto.org/docs/authoring/tables.html#disabling-quarto-table-processing

Order of Operations

The specified order of operations used when building tables is defined in the build.R file, which can be viewed on Github: https://github.com/vincentarelbundock/tinytable/tree/main/R

A few important things to note:

The i and j indices in format_tt() and style_tt() refer to the table structure after any grouping operations have been applied.
The theme argument in tt() is applied before any other theme, and pre-empts the default theme.
Theme functions apply transformations immediately when they are called, but they can delay the execution of certain operations using internal helpers: build_prepare() and build_finalize(). See theme_*() files in the Github repository for examples.
rbind() and rbind2() combine two tinytable objects before formatting. In some cases, this has the undesirable consequence of coercing numeric variables to character, which prevents further numeric formatting. To avoid this, users can apply format_tt() directly to the data frames before calling tt().

Examples

library(tinytable)
x <- mtcars[1:4, 1:5]

tt(x)
#> 
#> +------+-----+------+-----+------+
#> | mpg  | cyl | disp | hp  | drat |
#> +======+=====+======+=====+======+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 22.8 | 4   | 108  | 93  | 3.85 |
#> +------+-----+------+-----+------+
#> | 21.4 | 6   | 258  | 110 | 3.08 |
#> +------+-----+------+-----+------+ 

tt(x,
  theme = "striped",
  width = 0.5,
  caption = "Data about cars."
)
#> 
#> +------+-----+------+-----+------+
#> | mpg  | cyl | disp | hp  | drat |
#> +======+=====+======+=====+======+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 22.8 | 4   | 108  | 93  | 3.85 |
#> +------+-----+------+-----+------+
#> | 21.4 | 6   | 258  | 110 | 3.08 |
#> +------+-----+------+-----+------+
#> 
#> Table: Data about cars. 

tt(x, notes = "Hello World!")
#> 
#> +------+-----+------+-----+------+
#> | mpg  | cyl | disp | hp  | drat |
#> +======+=====+======+=====+======+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 21.0 | 6   | 160  | 110 | 3.90 |
#> +------+-----+------+-----+------+
#> | 22.8 | 4   | 108  | 93  | 3.85 |
#> +------+-----+------+-----+------+
#> | 21.4 | 6   | 258  | 110 | 3.08 |
#> +======+=====+======+=====+======+
#> | Hello World!                   |
#> +======+=====+======+=====+======+ 

fn <- list(i = 0:1, j = 2, text = "Hello World!")
tab <- tt(x, notes = list("*" = fn))
print(tab, "latex")
#> \begin{table}
#> \centering
#> \begin{talltblr}[         %% tabularray outer open
#> entry=none,label=none,
#> note{*}={Hello World!},
#> ]                     %% tabularray outer close
#> {                     %% tabularray inner open
#> colspec={Q[]Q[]Q[]Q[]Q[]},
#> hline{2}={1-5}{solid, black, 0.05em},
#> hline{1}={1-5}{solid, black, 0.08em},
#> hline{6}={1-5}{solid, black, 0.08em},
#> }                     %% tabularray inner close
#> mpg & cyl\textsuperscript{*} & disp & hp & drat \\
#> 21.0 & 6\textsuperscript{*} & 160 & 110 & 3.90 \\
#> 21.0 & 6 & 160 & 110 & 3.90 \\
#> 22.8 & 4 & 108 & 93 & 3.85 \\
#> 21.4 & 6 & 258 & 110 & 3.08 \\
#> \end{talltblr}
#> \end{table} 

k <- data.frame(x = c(0.000123456789, 12.4356789))
tt(k, digits = 2)
#> 
#> +----------+
#> | x        |
#> +==========+
#> | 0.00012  |
#> +----------+
#> | 12.43568 |
#> +----------+ 

# use variable labels stored in attributes as column names
dat = mtcars[1:5, c("cyl", "mpg", "hp")]
attr(dat$cyl, "label") <- "Cylinders"
attr(dat$mpg, "label") <- "Miles per Gallon"
attr(dat$hp, "label") <- "Horse Power"
tt(dat, colnames = "label")
#> 
#> +-----------+------------------+-------------+
#> | Cylinders | Miles per Gallon | Horse Power |
#> +===========+==================+=============+
#> | 6         | 21.0             | 110         |
#> +-----------+------------------+-------------+
#> | 6         | 21.0             | 110         |
#> +-----------+------------------+-------------+
#> | 4         | 22.8             | 93          |
#> +-----------+------------------+-------------+
#> | 6         | 21.4             | 110         |
#> +-----------+------------------+-------------+
#> | 8         | 18.7             | 175         |
#> +-----------+------------------+-------------+