# Guides for typesetting tables with the tabularray package

The LaTeX3 package tabularray provides a new way to typeset tables in a keyval way. This allows the separation of content and style, which can be very usefull in a lot of cases. However, almost all guides for typesetting tables are not written for the tabularray package, making it difficult for new users to use the package.

This post aims to simplify this by providing small guides for often asked questions. I know, that a lot of information will be similar to the tabularray documentation, which also provides good examples. However, the goal of this post is a guide/tutorial style and not just documentation.

## How to...

• use the basic syntax for creating simple tables?
• create cells spanning multiple columns and rows?
• use old and new interfaces?
• color columns, rows, cells and lines?
• create custom column and row types?
• use longtblr for creating tables spanning multiple pages?
• use templates and styles to customize the table appearance?
• typeset tables with booktabs commands?
• use siunitx for columns with numeric input?

If there is anything missing or unnescessary in the list, please add or delete items. This also helps answer writers to know, which topics are still unclear.

• Give context which packages have been used "traditionally" to create the output, e.g. table option of xcolor for coloring cells.
• If sensible, provide information for both the old and new interfaces, allowing users to choose which approach they prefer. I find mixing both the most flexible approach.
• Refer to the official documentation, so users know where to look if there want more advanced features.

PS: I am new to the idea of community wiki posts, so if there is anything wrong with this, feel free to edit. Maybe this list is unnescessary, because people can also use the documentation. I just thought that a few simple guides are more accesible than the whole documentation. If this is a stupid idea, let me know. Also, since I am not a native speaker, you are welcome to improve my writing.
• Apparently, I cannot make this post community wiki myself. If any moderators think this post is usefull, please make this community wiki.
– marv
Jan 8 at 13:14
• The documentation (texdoc link) does have "simple examples" however. (chapter 1 "overview of features"). Maybe the post is still useful, we will know by the number of upvotes over a few years. Jan 9 at 12:27

# Creating cells that span multiple columns or rows

This guide explains, how to create cells that span multiple rows using the \SetCell command and cell key. It is specifically intended for users which are familiar with the \multicolumn and \multirow commands.

Let's take a look as a simple example taken from here. On the left is the solution using the tabular environment with \multicolumn and \multirow, while the right side shows the same table using the tblr environment and \SetCell command.

As you can see in the code below, the syntax is very similar. \multicolumn{<ncols>} is replaced by \SetCell[c=<ncols>] and \multirow{<nrows>} by \SetCell[r=<nrows>}. Note that you don' need curly braces for the content when using \SetCell. The optional argument of \SetCell accepts the keys r=<nrows> and c=<ncols>, whereas the mandatory argument if often used for setting the alignments such as l, c, r and j for horizontal aligment and t, m, b, h and f for vertical aligment. See the remarks at the end of this answer for further explanation about alignment.

The mandatory argument of \SetCell is not limited to aligment keys. It allows for many more usefull keys, such as the color of background and foreground. Please have a look at the table "Keys for the Contents of Cells" in the documentation.

Important In this particular case, you could ditch the ampersands in row 1 after "Team sheet" and still get the same result. However, this does not work when you have content following in the row. This behaviour differs from \multicolumn, so remember this when some cells appear to vanish. When working with large tables, it is recommended to name the unused cells, e.g. as in the second code example below.

Additionally, the tblr solution has more vertical spacing between rows, making it easier to read the table. The spacing can be controlled by several keys in the mandatory argument, which can be found in the table "Keys for Rows" in the documentation.

%%% Code for tabular
%\usepackage{multirow}
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{Team sheet} \\
\hline
Goalkeeper & GK & Paul Robinson \\ \hline
\multirow{4}{*}{Defenders} & LB & Lucas Radebe \\
& DC & Michael Duburry \\
& DC & Dominic Matteo \\
& RB & Didier Domi \\ \hline
\multirow{3}{*}{Midfielders} & MC & David Batty \\
& MC & Eirik Bakke \\
& MC & Jody Morris \\ \hline
Forward & FW & Jamie McMaster \\ \hline
\multirow{2}{*}{Strikers} & ST & Alan Smith \\
& ST & Mark Viduka \\
\hline
\end{tabular}

%%% Code for tblr
%\usepackage{tabularray}
\begin{tblr}{|l|l|l|}
\hline
\SetCell[c=3]{c} Team sheet && \\
\hline
Goalkeeper & GK & Paul Robinson \\ \hline
\SetCell[r=4]{l} Defenders some really & LB & Lucas Radebe \\
& DC & Michael Duburry \\
& DC & Dominic Matteo \\
& RB & Didier Domi \\ \hline
\SetCell[r=3]{l} Midfielders & MC & David Batty \\
& MC & Eirik Bakke \\
& MC & Jody Morris \\ \hline
Forward & FW & Jamie McMaster \\ \hline
\SetCell[r=2]{l} Strikers & ST & Alan Smith \\
& ST & Mark Viduka \\
\hline
\end{tblr}


## Using the new keyval interface of tabularray

Every aspect of formatting the table can also be controlled via the new keyval interface in the mandatory argument of \begin{tblr}. For example, if you want to typeset the exact same table as in the previous tabular solution, you could do something like this.

\begin{tblr}{
colspec=lll, rowsep=0pt,
vlines, hline{1,2,3,7,10,11,13},
cell{1}{1}={c=3}{c}, cell{3}{1}={r=4}{l},
cell{7}{1}={r=3}{l}, cell{11}{1}={r=2}{l},
}
Team sheet & 1-2 & 1-3 \\
Goalkeeper & GK & Paul Robinson \\
Defenders & LB & Lucas Radebe \\
4-1 & DC & Michael Duburry \\
5-1 & DC & Dominic Matteo \\
6-1 & RB & Didier Domi \\
Midfielders & MC & David Batty \\
8-1 & MC & Eirik Bakke \\
9-1 & MC & Jody Morris \\
Forward & FW & Jamie McMaster \\
Strikers & ST & Alan Smith \\
12-1 & ST & Mark Viduka \\
\end{tblr}


When using multiple keys, you have to put the columns specification in the key colspec. rowsep=0pt removes the extra vertical spacing (this is just an example, please consider keeping the spacing as it makes the table more readable). The vlines and hline keys are for the vertical and horizontal lines respectively. The \SetCell[<span>{<styles>} at cell in row i and j is replaced by the option cell{i}{j}={<span>}{<styles>}. Note the curly braces for <span>. The unused cells are also numbered with their respective row and column number. This makes it easier to keep track of ampersands when working with large tables. The content of these cells is ignored for typesetting.

As you can see, the format is now completely separated from the content. This can be very usefull, e.g. when you get your table data from an external ressource. For a full comparision between the two interfaces, read the table "Old Interfaces and New Interfaces" in the documentation.

You can mix both interfaces in your tblr environment as you like. For example, you can choose spacing and horizontal and vertical lines in the New Interface and use the \SetCell command in the old interface.

That concludes the short introduction to typesetting multicolumn and multirow cells using the tabularray package. If you think there is something wrong or missing, feel free to improve this answer.

Remark 1: For a multirow cell, vertical aligment t, m and b are the same: any one of them will put cell text in the middle. You may use h or f alignment if you want to align the top/bottom baseline of a multirow cell with that of a single-row cell in another column.

Remark 2: For a single-row cell, default vertical aligment is t (top), while for a multirow cell, default vertical aligment is m (middle).

• Thanks for adding this information. I was just browsing through the code, if there is a different vertical alignment when r>1, because I stumbled on this while writing the answer.
– marv
Jan 9 at 15:25
• I have added two remarks which are missing in the documentation to the end of your answer. Feel free to move them to the appropriate positions. Jan 9 at 15:25

# Coloring columns, rows, cells and lines

This guide explains how to use colors in tblr tables. You will learn how to color columns, rows, individual cells and horizontal and vertical lines. For users familiar with the \columncolor, \rowcolor and cellcolor commands, analogous tabularray commands will be provided.

Let's take a look at a ugly but colorfull example. On the left is the solution using the tabular environment with commands defined by \usepackage[table]{xcolor}, while the right side shows the same table using the tblr environment.

Excerpt for some extra vertical spacing, the tables look identical. In the code below, you can also see that the code is very similar. \rowcolor and \cellcolor are replaced by \SetRow and \SetCell respectively. Note that \SetRow is not needed in row 1, because the color is set in the \SetCell command.

Coloring columns is done with \columncolor in the xcolor syntax. A user can use > in the column definition or define a new column type, e.q. the a column in the example. With tabularray, you can specify a color using the primitive Q column type. Of course, you can also define a new column type with \NewColumnType, see column A for an example. Note The Q column type supports usefull keys, e.g. vertical alignment, font color and many more. See the table "Keys for Columns" in the documentation.

The appearance of horizontal and vertical lines in tabular environment can be customized by commands such as \arrayrulewidth and \arrayrulecolor. tabularray provides see keys hlines and vlines for setting horizontal and vertical lines respectively. Note that you don't need the \hline commands in the table content.

%%% Code for tabular
%\usepackage[table]{xcolor}
\newcolumntype{a}{ >{\columncolor{yellow!50}} l }
\setlength{\arrayrulewidth}{2pt}
\arrayrulecolor{gray}
\begin{tabular}{|a|>{\columncolor{red!50}}r|r|}
\hline
\rowcolor{green} \multicolumn{3}{|c|}{{\LARGE \textcolor{red}{StackExchange Sites}}} \\ \hline
\rowcolor{blue!50} Site & questions & answers \\ \hline
Stack Overflow & 22m & 33m \\ \hline
Mathematics & 1.5m & \cellcolor{magenta} 2m \\ \hline
Super User & 472k & 684k \\ \hline
\rowcolor{orange!50} TeX - LaTeX & 228k & 293k \\ \hline
\end{tabular

%%% Code for tblr
%\usepackage{tabularray}
\NewColumnType{A}{Q[l, yellow!50]}
\begin{tblr}{colspec={AQ[r,red!50]r}, hlines={2pt, gray}, vlines={2pt, gray}}
\SetCell[c=3]{c, green, fg=red, font=\LARGE} StackExchange Sites && \\
\SetRow{blue!50} Site & questions & answers \\
Stack Overflow & 22m & 33m \\
Mathematics & 1.5m & \SetCell{magenta} 2m \\
Super User &  472k & 684k \\
\SetRow{orange!50} TeX - LaTeX & 228k & 293k \\
\end{tblr}


Remark Small lines are sometimes not correctly rendered, when using the xcolor commands. Additionaly, \cline commands don't work. Both of these issues are not present when using the tabularray syntax.

## Using the new keyval interface of tabularray

tabularray also has a new keyval interface allowing you to customize the format of the table in the mandatory argument of \begin{tblr}. Using this new syntax, the table can be created with

\begin{tblr}{
colspec={lrr}, hlines={2pt, gray}, vlines={2pt, gray},
column{1} = {yellow!50}, column{2} = {red!50},
row{2} = {blue!50}, row{Z} = {orange!50},
cell{1}{1} = {c=3}{c, green, fg=red, font=\LARGE},
cell{4}{3} = {magenta},
}
StackExchange Sites && \\
Site & questions & answers \\
Stack Overflow & 22m & 33m \\
Mathematics & 1.5m & 2m \\
Super User &  472k & 684k \\
TeX - LaTeX & 228k & 293k \\
\end{tblr}


You can specify columns and rows using the column and row keys respectively. The \SetCell[<span>{<styles>} at cell in row i and j is replaced by the option cell{i}{j}={<span>}{<styles>}. For example, cell{1}{1} = {c=3}{c, green, fg=red, font=\LARGE} sets the cell in the first row and column to span 3 columns {c=3}, centered c, with green background color, red font color and LARGE font. For a full list of options, have a look at the tables "Keys for the Content of Cells", "Keys for Rows" and "Keys for Columns" in the documentation.

You can mix both interfaces in your tblr environment as you like. For example, you can specify the columns and rows keys and use the \SetCell for customizing individual cells.

## Color alternating rows

Another often wanted style is to color alternating rows with different colors. With \usepackage[table]{xcolor} you can use the command \rowcolors{<start-row>}{<odd-row-color>}{<even-row-color>} for this. tabularray provides the selectors odd and even, which can be used in the row and column keys. As of now, specifying odd and even from a specified starting index is not supported. The feature will be added soon (see here). In the meantime you have to override the cells which should not be colored, as in the example below.

\begin{tblr}{
colspec={lrr}, hlines,
row{even} = {blue!20},
row{odd} = {red!20},
row{1} = {white, font=\large\bfseries},
}
Site & questions & answers \\
Stack Overflow & 22m & 33m \\
Mathematics & 1.5m & 2m \\
Super User &  472k & 684k \\
TeX - LaTeX & 228k & 293k \\
\end{tblr}


The odd and even selectors can also produce more complex patterns, e.g. a chesboard.
Very advanced users can also define custom selectors with \NewChildSelector (see an example), but that is beyond the scope of this guide.
That concludes the short introduction for using colors with the tabularray package. If you think there is something wrong or missing, feel free to improve this answer.
• In fact, \columncolor, \rowcolor and \cellcolor commands are provided by colortbl package. And \usepackage[table]{xcolor} loads colortbl package. To typeset colorful tables, colortbl needs color or xcolor package, and tabularray need xcolor and ninecolors packages. Jan 31 at 7:09