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

Captions and labels

Due to a quirk in Quarto reported here, captions in Typst and Quarto documents need to be specified using both the tbl-cap and the label chunk option:

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

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.

Quarto

Custom crossref styles

In Quarto, it is possible to create a custom crossref type for things like appendix tables. One challenge, is that LaTeX will not allow users to nest a tblr environment, inside a table environment, inside the new environment that Quarto creates for the crossref. Therefore, when rendering a table to LaTeX/PDF, it is important to drop the \begin{table} environment. This can be done using the theme_tt() function.

In the example below, we call theme_tt() explicitly for a single table, but the themes vignette shows how to set a global theme using the tinytable_tt_theme option.

---
title: "Crossref Example"
format:
  pdf: default
  html: default
crossref:
  custom:
    - kind: float
      key: apptbl
      latex-env: apptbl
      reference-prefix: Table A
      space-before-numbering: false
      latex-list-of-description: Appendix Table
apptbl-cap-location: top
---

See @apptbl-testing

::: {#apptbl-testing}

```{r}
library(tinytable)

tt(mtcars[1:5,]) |> theme_tt("tabular", style = "tabularray")
```

Caption goes here.

:::

Sub-captions

With version 0.4.0 of tinytable and versions above 1.6 of Quarto—only available as a pre-release build at the time of writing— users can specify sub-captions for tables. This is done by adding a tbl-subcap chunk option to the table chunk. We also need to use a tinytable theme to remove built-in table structure and let Quarto handle the table construction. Here is a simple example document:

---
format: pdf
---

See @tbl-example, @tbl-example-1, or @tbl-example-2.

```{r}
#| label: tbl-example
#| tbl-cap: "Example"
#| tbl-subcap: 
#|   - "Cars"
#|   - "Pressure"
#| layout-ncol: 2

library(tinytable)
tt(head(cars)) |> theme_tt("tabular", style = "tabularray")
tt(head(pressure)) |> theme_tt("tabular", style = "tabularray")
```

Same table, different styles

In some cases, the user wants to print a single table multiple times with different styles in a single HTML document. This will sometimes cause issues, because the style_tt() function inserts several javascript functions to modify the same table, thus creating conflicts. A simple solution is to change the unique ID of the table object manually.

Consider this RevalJS slideshow in which we sequentially highlight different rows of the data frame:

---
format: revealjs
---

## Page 1

```{r}
library(tinytable)

tab <- tt(head(iris))
tab
```

## Page 2

```{r}
tab@id <- "table_01"
tab |> style_tt(i = 3, background = "skyblue")
```

## Page 3

```{r}
tab@id <- "table_02"
tab |> style_tt(i = 5, background = "orange")
```