FAQ

HTML

LaTeX

Preamble

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

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

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

setspace

Some users have encountered unexpected spacing behavior when generating tables that are not wrapped in a \begin{table} environment (ex: multipage or raw tblr).

One issue stems from the fact that the \begin{table} environment resets any spacing commands in the preamble or body by default, such as:

\usepackage{setspace}
\doublespacing

This means that when using theme_tt("multipage") —which does not wrap the table in a table environment— the spacing is not reset, and tables are double spaced. This is not a bug, since double-spacing is in fact what the user requested. Nevertheless, the behavior can seem surprising for those used to the automagical table environment spacing reset.

One workaround is to add the following to the document preamble when using multipage/longtblr:

\usepackage{etoolbox}
\AtBeginEnvironment{longtblr}{\begin{singlespacing}}
\AtEndEnvironment{longtblr}{\end{singlespacing}}

Example Quarto doc:

---
title: longtblr and setspacing
format:
  pdf:
    include-in-header:
      - text: |
         % Tinytable preamble
         \usepackage{tabularray}
         \usepackage{float}
         \usepackage{graphicx}
         \usepackage{codehigh}
         \usepackage[normalem]{ulem}
         \UseTblrLibrary{booktabs}
         \UseTblrLibrary{siunitx}
         \newcommand{\tinytableTabularrayUnderline}[1]{\underline
         {#1}}
         \newcommand{\tinytableTabularrayStrikeout}[1]{\sout{#1}}
         \NewTableCommand{\tinytableDefineColor}[3]{\definecolor{
         #1}{#2}{#3}}
         % Spacing Commands
         \usepackage{setspace}
         \doublespacing
         % Fix Spacing in longtblr
         \usepackage{etoolbox}
         \AtBeginEnvironment{longtblr}{\begin{singlespacing}}
         \AtEndEnvironment{longtblr}{\end{singlespacing}}
---

```{=latex}
\begin{longtblr}[         %% tabularray outer open
]                     %% tabularray outer close
{                     %% tabularray inner open
colspec={Q[]Q[]Q[]Q[]},
}                     %% tabularray inner close
\toprule
foo & bar & baz \\
foo & bar & baz \\
foo & bar & baz \\
\bottomrule
\end{longtblr}
```

Global styles

tabularray allows very powerful styling and themeing options. See the reference manual for more information.

For example, you can change the size of footnotes in all tables of a document with:

---
format: 
    pdf:
        keep-tex: true
        header-includes: |
            \SetTblrStyle{foot}{font=\LARGE}
---

```{r}
library(tinytable)
library(magrittr)
tt(head(iris), notes = "Blah blah")
```

Beamer

Due to a bug in the upstream package rmarkdown, Quarto or Rmarkdown presentations compiled to Beamer cannot include adequate package loading commands in the preamble automatically. This bug prevents tinytable::usepackage_latex() from modifying the preamble. Here’s a workaround.

Save this LaTeX code as preamble.tex:

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

Then, load preamble.tex in your YAML header:

---
output: 
  beamer_presentation:
    includes:
      in_header: preamble.tex
---

With these changes, the table should appear with colors as expected.

Typst

Quarto

By default tinytable uses Quarto’s own figure handling to set captions and figure blocks. This allows cross-references to work. For this to work well, users should specify both the table label and the table caption explicitly using chunk options. Note that the label must imperatively start with tbl-:

#| label: tbl-example
#| tbl-cap: This is an example table
library(tinytable)
tt(head(iris))

Alternatively, users can disable Quarto table handling and rely on internal tinytable options instead.

options(tinytable_quarto_figure = FALSE)

Doing this will prevent styles to bleed over from one table to the next.

Multi-page long tables

The Typst tables created by tinytable are automatically broken across pages with repeated headers. However, in Quarto documents, the Quarto software wraps tables in an non-breakable #figure environment. This can break the display of long tables. One solution is to use a raw Typst code block to set Figures to be breakable:

---
format: typst
---

```{=typst}
#show figure: set block(breakable: true)
```

```{r}
#| tbl-cap: "blah blah blah"
#| label: tbl-blah
library(tinytable)
tt(head(iris, 50))
```

Markdown

style_tt() does not apply to row headers

This is an important limitation, but it is difficult to get around. See this issue for discussion: https://github.com/vincentarelbundock/tinytable/issues/125

Users can use markdown styling directly in group_tt() to circumvent this. This is documented in the tutorial.

rowspan and colspan

These arguments are already implemented in the form of “pseudo-spans”, meaning that we flush the content of adjacent cells, but do not modify the row or column borders. This is probably adequate for most needs.

One alternative would be to remove line segments in finalize_grid(). I tried this but it is tricky and the results were brittle, so I rolled it back. I’m open to considering a PR if someone wants to contribute code, but please discuss the feature design in an issue with me before working on this.

Word (.docx)

Word document documents are created in two steps:

  1. Generates a markdown table.
  2. Call the external Pandoc software to convert the markdown table to a Word document.

This workflow limits the range of styling options available in Word. Indeed, many arguments in the style_tt() function do not have formal markdown notation to represent them, and are thus not available. For example, while italic, bold, and strikeout, are supported, color and background are not.

Note that other tinytable functions such as group_tt() and format_tt() and plot_tt() should work as expected in Word.

Users who want full styling capabilities in Word can save tables as image files and insert them in their documents. Here is an example Quarto notebook illustrating this workflow.

---
format: docx
---

```{r}
#| out-width: "50%"
library(tinytable)

options(tinytable_save_overwrite = TRUE)

tt(mtcars[1:10, 1:5]) |>
  style_tt(j = 2:3, background = "black", color = "white") |>
  save_tt("table_01.png")

knitr::include_graphics("table_01.png")
```