tikz.dev / tcolorbox Manual

The tcolorbox package

Libraries

16 Library raster

The library is loaded by a package option or inside the preamble by:

16.1 Concept of Rasters

A raster is used to align several colored boxes in a regular way. It can be seen as a far related counterpart to the matrix construct of TikZ, but it differs in many aspects.

In principle, tcolorboxes are arranged in rows and columns when put inside a tcbraster environment. The boxes are fluently added to the raster like adding text to a paragraph. Especially, line/row breaks are done automatically and one cannot end a line/row ahead of schedule. Further, a raster is not restricted to a single page but may break into an arbitrary series of pages.

Compiled output
Compiled output
Compiled output
16.2 Macros of the Library
  • \tcbitem[⟨options⟩]New: 2014-11-10

  • Used inside tcbitemize to create a new tcolorbox with the given ⟨options⟩.

16.3 Option Keys of the Library
  • /tcb/raster rows=⟨number⟩(no default, initially 2)New: 2014-11-10

  • Sets the ⟨number⟩ of rows for a raster. Note that this is only relevant in connection with setting /tcb/raster height to a value greater than 0pt. Then, it defines the number of rows per given height.

  • /tcb/raster before skip=⟨glue⟩(no default, initially 2mm)New: 2014-11-10Updated: 2014-12-16

  • Space of the given ⟨glue⟩ is inserted vertically before the raster. This space is discardable.

  • /tcb/raster after skip=⟨glue⟩(no default, initially 2mm)New: 2014-11-10Updated: 2014-12-16

  • Space of the given ⟨glue⟩ is inserted vertically after the raster. This space is discardable.

  • /tcb/raster halign=⟨alignment⟩(no default, initially left)New: 2014-11-10

  • Defines the horizontal alignment for the boxes of the rows of a raster, if these rows are not completely filled (mainly: the last one).

    Feasible values for ⟨alignment⟩ are:

    • left: align to the left side,

    • center: align to the center,

    • right: align to the right side.

    Compiled output

    \begin{tcbitemize}[raster halign=center,
    size=small,colframe=red!50!black,colback=red!10!white]
    \tcbitem One
    \tcbitem Two
    \tcbitem Three
    \end{tcbitemize}
16.4 Adding Styles for Specific Boxes

The following styles can be defined to address certain boxes inside a raster. Note that such style definitions are not removed by /tcb/reset or /tcb/raster reset. The style definitions are used in the order given below.

  • /tcb/raster every box(style)New: 2014-11-24

  • This style is used for every box.

  • /tcb/raster even column(style)New: 2014-11-10

  • This style is used for every box in an even column.

  • /tcb/raster column n(style)New: 2014-11-10

  • This style is used for every box in the n-th column. n has to be replaced by a number.

  • /tcb/raster odd row(style)New: 2014-11-10

  • This style is used for every box in an odd row.

  • /tcb/raster even row(style)New: 2014-11-10

  • This style is used for every box in an even row.

  • /tcb/raster odd number(style)New: 2014-11-10

  • This style is used for every box with an odd number.

  • /tcb/raster row m column n(style)New: 2014-11-10

  • This style is used for the box in the m-th row and n-th column. m and n have to be replaced by numbers.

16.5 Combining Columns or Rows
16.6 Rasters inside Rasters

A raster inside a raster cannot be used directly, because a raster can only contain a tcolorbox or something derived from a tcolorbox. So, a raster can be put inside a tcolorbox inside a raster.

Some examples for such constructions can be found at tcboxedraster, /tcb/raster multicolumn, /tcb/raster multirow.

16.6.1 Raster Setup

The intermediating tcolorbox can be made invisible by using /tcb/blankest.

Compiled output

\begin{tcbraster}[raster equal height=rows,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\begin{tcolorbox}[blankest]
\begin{tcbraster}[raster columns=1]
\begin{tcolorbox}One\end{tcolorbox}
\begin{tcolorbox}Two\end{tcolorbox}
\end{tcbraster}
\end{tcolorbox}
\begin{tcolorbox}raster+tcolorbox+raster\end{tcolorbox}
\end{tcbraster}

Compiled output

\begin{tcbraster}[raster equal height=rows,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\begin{tcboxedraster}[raster columns=1]{blankest}
\begin{tcolorbox}One\end{tcolorbox}
\begin{tcolorbox}Two\end{tcolorbox}
\end{tcboxedraster}
\begin{tcolorbox}raster+tcboxedraster\end{tcolorbox}
\end{tcbraster}

Compiled output

\begin{tcbitemize}[raster equal height=rows,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\tcbitem[blankest]
\begin{tcbitemize}[raster columns=1]
\tcbitem One
\tcbitem Two
\end{tcbitemize}
\tcbitem tcbitemize+tcbitem+tcbitemize
\end{tcbitemize}
16.6.2 Placing Spaces

If the heights of boxes inside staggered rasters should be matched, the space has to be distributed accordingly.

Compiled output

\begin{tcbitemize}[raster rows=2,raster height=6cm,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\tcbitem[blankest]
\begin{tcbitemize}[raster columns=1,raster rows=2,raster height=\tcbtextheight]
\tcbitem One
\tcbitem Two
\end{tcbitemize}
\tcbitem This is a fixed height box.
\tcbitem Three
\tcbitem Four
\end{tcbitemize}

Compiled output

\begin{tcbitemize}[raster columns=4,raster rows=4,raster height=0.8\linewidth,
raster every box/.style={size=small,beamer,
colframe=blue!75!yellow,colback=red!75!yellow!20,
center title,title=Box}]
\tcbitem One
\tcbitem Two
\tcbitem Three
\tcbitem Four
\tcbitem[raster multirow=2,blankest]
\begin{tcbitemize}[raster columns=1,raster rows=2,raster height=\tcbtextheight]
\tcbitem Twelve
\tcbitem Eleven
\end{tcbitemize}
\tcbitem[raster multirow=2,raster multicolumn=2,
colframe=red!75!yellow,colback=blue!75!yellow!20]
This is an example with fixed height boxes.
\tcbitem[raster multirow=2,blankest]
\begin{tcbitemize}[raster columns=1,raster rows=2,raster height=\tcbtextheight]
\tcbitem Five
\tcbitem Six
\end{tcbitemize}
\tcbitem Ten
\tcbitem Nine
\tcbitem Eight
\tcbitem Seven
\end{tcbitemize}

Compiled output

\begin{tcbitemize}[raster equal height=rows,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\tcbitem[blankest,space to=\myspace]
\begin{tcbitemize}[raster columns=1]
\tcbitem One
\tcbitem[add to natural height=\myspace]
This box will adapt its height.
\end{tcbitemize}
\tcbitem This is a flexible height box.
\tcbitem \lipsum[4]
\tcbitem[blankest,space to=\myspace]
\begin{tcbitemize}[raster columns=1]
\tcbitem One
\tcbitem[add to natural height=\myspace]
This box will adapt its height.
\end{tcbitemize}
\end{tcbitemize}

Compiled output

\begin{tcbitemize}[raster equal height=rows,
raster every box/.style={colframe=red!50!black,colback=red!10!white}]
\tcbitem[blankest,space to=\myspace]
\begin{tcbitemize}[raster columns=1]
\tcbitem One
\tcbitem[add to natural height=\myspace]
This box will adapt its height.
\tcbitem \lipsum[4]
\end{tcbitemize}
\tcbitem[blankest,space to=\myspace]
\begin{tcbitemize}[raster columns=1]
\tcbitem[blankest]\includegraphics[width=\linewidth]{goldshade.png}
\tcbitem[add to natural height=\myspace]
This box will adapt its height.
\end{tcbitemize}
\end{tcbitemize}