% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tt.R
\name{tt}
\alias{tt}
\alias{tt.default}
\title{Draw a Tiny Table}
\usage{
tt(x, ...)

\method{tt}{default}(
  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),
  engine = NULL,
  ...
)
}
\arguments{
\item{x}{A data frame, data table, or tibble to be rendered as a table.}

\item{...}{Additional arguments are ignored}

\item{digits}{Number of significant digits to keep for numeric variables. When \code{digits} is an integer, \code{tt()} calls \code{format_tt(x, digits = digits)} before proceeding to draw the table. Note that only the \code{digits} argument is passed explicitly; all other \code{format_tt()} arguments use their default values, which can be influenced by global options (e.g., \code{options(tinytable_format_num_fmt = "decimal")}). When \code{digits} is \code{NULL} (the default), \code{format_tt()} is not called at all, so global \verb{tinytable_format_*} options have no effect unless the user calls \code{format_tt()} explicitly. Users who need more control can use the \code{format_tt()} function instead.}

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

\item{notes}{Notes to append to the bottom of the table. This argument accepts several different inputs:
\itemize{
\item Single string insert a single note: \code{"blah blah"}
\item Multiple strings insert multiple notes sequentially: \code{list("Hello world", "Foo bar")}
\item A named list inserts a list with the name as superscript: \code{list("a" = list("Hello World"))}
\item A named list with positions inserts markers as superscripts inside table cells: \code{list("a" = list(i = 0:1, j = 2, text = "Hello World"))}
}}

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

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

\item{theme}{Function or string.
\itemize{
\item String: grid, revealjs, rotate, striped, empty
\item Function: Applied to the \code{tinytable} object.
}}

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

\item{rownames}{Logical. If \code{TRUE}, rownames are included as the first column}

\item{escape}{Logical. If \code{TRUE}, escape special characters in the table. Equivalent to \code{format_tt(tt(x), escape = TRUE)}.}

\item{engine}{Character string specifying the HTML engine: "tinytable", "bootstrap", or "tabulator". Equivalent to \code{theme_html(tt(x), engine = engine)}. When \code{NULL} (the default), the \code{tinytable_html_engine} global option is honored by \code{theme_html()}.}
}
\value{
An object of class \code{tt} representing the table.

The table object has S4 slots which hold information about the structure of the table. For example, the \code{table@group_index_i} slot includes the row indices for grouping labels added by \code{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 \code{tinytable} developers do not consider changes to the internal structure of the output object to be a "breaking  change" for versioning or changelog purposes.
}
\description{
The \code{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:
\itemize{
\item \code{style_tt()}: style fonts, colors, alignment, etc.
\item \code{format_tt()}: format numbers, dates, strings, etc.
\item \code{group_tt()}: row or column group labels.
\item \code{save_tt()}: save the table to a file or return the table as a string.
\item \code{print()}: print to a specific format, ex: \code{print(x, "latex")}
\item \verb{theme_*()} functions apply a collection of format-specific or visual transformations to a \code{tinytable.}
}

\code{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 \code{print(x, output="markdown")} to print the table in a specific format. Alternatively, they can set a global option: \code{options("tinytable_print_output"="markdown")}
}
\section{Dependencies}{

\itemize{
\item \code{.pdf} output requires a full LaTeX installation on the local computer.
\item \code{.png} output requires the \code{webshot2} package.
\item \code{.html} self-contained files and \code{theme_typst(portable = TRUE)} require the \code{base64enc} package.
}
}

\section{LaTeX preamble}{


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

When rendering a document from Quarto or Rmarkdown directly to PDF, \code{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 \verb{#| cache: false} for the chunk(s) where you use tinytable.

\if{html}{\out{<div class="sourceCode latex">}}\preformatted{\\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\}\}
}\if{html}{\out{</div>}}
}

\section{Markdown limitations}{


Markdown is a text-only format that only supports these styles: italic, bold, strikeout. The \code{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, \code{tinytable} can display colors and text styles using
ANSI escape codes by setting \code{theme_markdown(ansi = TRUE)}. This allows for rich formatting in
compatible terminal environments.
}

\section{Word limitations}{


Word tables only support these styles: italic, bold, strikeout. The \code{width} argument is also unavailable.
Moreover, the \code{style_tt()} function cannot be used to style headers inserted by the \code{group_tt()} function;
instead, you should style the headers directly in the header definition using markdown syntax:
\code{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.
}

\section{Tabulator (interactive tables)}{


\strong{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.

\strong{Features:}
\itemize{
\item Sorting and filtering of all columns
\item Pagination with configurable page sizes
\item Search functionality across all columns
\item Multiple CSS themes and custom styling
\item Real-time data export options
\item Accessibility features (ARIA compliant)
}

\strong{Limitations:}
\itemize{
\item \code{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 \code{align}/\code{alignv} with \code{i} argument not supported)
\item Row-based formatting (\code{format_tt()} with \code{i} argument) not supported
\item Global stylesheets affect all tables in multi-table documents
\item Date formatting uses Luxon tokens, not R's \code{strptime} format
\item Boolean formatting requires \code{format_tt()} with \code{bool} argument for custom display
}
}

\section{Global options}{


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

\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(tinytable_tt_digits = 4)
tt(head(iris))
}\if{html}{\out{</div>}}

You can set options in a script or via \code{.Rprofile}. Note: be cautious with \code{.Rprofile} settings as they may affect reproducibility.
\subsection{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 \code{digits} argument of the \code{tt()} function globally, call:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{options(tinytable_tt_digits = 4)
}\if{html}{\out{</div>}}

In addition, some more specific options are available to control the behavior of the package in specific contexts.
\itemize{
\item \code{tinytable_html_mathjax}: Insert MathJax scripts (warning: may conflict if MathJax is loaded elsewhere)
\item \code{tinytable_pdf_clean}: Delete temporary and log files for pdf output in \code{save_tt()}
\item \code{tinytable_color_name_normalization}: Enable/disable automatic color name processing (default: TRUE). When enabled, R color names recognized by \code{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.
}
\subsection{Quarto}{

The \code{format_tt(quarto=TRUE)} argument enables Quarto data processing with some limitations:
\enumerate{
\item The \verb{\\QuartoMarkdownBase64\{\}} LaTeX macro may not process references and markdown as expected
\item Quarto processing may conflict with \code{tinytable} styling/formatting
}

Options:
\itemize{
\item \code{tinytable_quarto_disable_processing}: Disable Quarto cell processing
}

Example of Quarto-specific code in cells:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{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)
}\if{html}{\out{</div>}}

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

}
}

\section{Order of Operations}{


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

A few important things to note:
\itemize{
\item The \code{i} and \code{j} indices in \code{format_tt()} and \code{style_tt()} refer to the table structure \emph{after} any grouping operations have been applied.
\item The \code{theme} argument in \code{tt()} is applied before any other theme, and pre-empts the default theme.
\item Theme functions apply transformations immediately when they are called, but they can delay the execution of certain operations using internal helpers: \code{build_prepare()} and \code{build_finalize()}. See \verb{theme_*()} files in the Github repository for examples.
\item \code{rbind()} and \code{rbind2()} combine two \code{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 \code{format_tt()} directly to the data frames before calling \code{tt()}.
}
}

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

tt(x)

tt(x,
  theme = "striped",
  width = 0.5,
  caption = "Data about cars."
)

tt(x, notes = "Hello World!")

fn <- list(i = 0:1, j = 2, text = "Hello World!")
tab <- tt(x, notes = list("*" = fn))
print(tab, "latex")

k <- data.frame(x = c(0.000123456789, 12.4356789))
tt(k, digits = 2)

# 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")

}
