tikz.dev / tcolorbox Manual

The tcolorbox package

Libraries

10 Library skins

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

\tcbuselibrary{skins}

This also loads the package tikzfill.image.

In the following, general settings and options of the library are documented. The actual catalog of skins is found in Section 11.

10.1 Style Option Keys

The following style options are applicable for all skins which use engines of type path, pathfirst, pathmiddle, or pathlast. Especially, the skin enhanced supports all of them and standard none.

  • /tcb/frame style=⟨tikz keys⟩(style, no default)

    • The ⟨tikz keys⟩ are used inside the TikZ path command for drawing the frame of the box.
    This option is available if the /tcb/frame engine is set to path, pathfirst, pathmiddle, or pathlast. It is not available for standard.

    Compiled output

    \tcbset{colback=red!5!white,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    frame style={left color=red!75!black,
    right color=blue!75!black}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

  • /tcb/frame style tile={⟨graphics options⟩}{⟨file name⟩}(no default, initially unset)

    • Fills the frame with a tile pattern based on an external image referenced by ⟨file name⟩. The ⟨graphics options⟩ are given to the underlying \includegraphics command.

    Compiled output

    \tcbset{colback=red!5!white,coltitle=red!30!black,
    opacityback=0.75,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    frame style tile={width=1cm}{pink_marble.png}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

  • /tcb/interior style=⟨tikz keys⟩(style, no default)

    • The ⟨tikz keys⟩ are used inside the TikZ path command for drawing the interior of the box. They are used for the titled and for the untitled version as well.
    This option is available if the /tcb/interior titled engine or /tcb/interior engine is set to path, pathfirst, pathmiddle, or pathlast. It is not available for standard.

    Compiled output

    \tcbset{colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    interior style={left color=red!20!white,
    right color=yellow!50!white}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

  • /tcb/interior style tile={⟨graphics options⟩}{⟨file name⟩}(no default, initially unset)

    • Fills the interior with a tile pattern based on an external image referenced by ⟨file name⟩. The ⟨graphics options⟩ are given to the underlying \includegraphics command.

    Compiled output

    \tcbset{colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    interior style tile={width=2cm}{crinklepaper.png}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

  • /tcb/title style=⟨tikz keys⟩(style, no default)

    • The ⟨tikz keys⟩ are used inside the TikZ path command for drawing the title area of the box.
    This option is available if the /tcb/title engine is set to path, pathfirst, pathmiddle, or pathlast. It is not available for standard.

    Compiled output

    \tcbset{colback=red!5!white,colframe=red!75!black,
    coltitle=blue!50!black,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    title style={left color=blue!15!yellow,
    right color=red!85!black}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

  • /tcb/title style tile={⟨graphics options⟩}{⟨file name⟩}(no default, initially unset)

    • Fills the title area with a tile pattern based on an external image referenced by ⟨file name⟩. The ⟨graphics options⟩ are given to the underlying \includegraphics command.

    Compiled output

    \tcbset{colback=red!5!white,colframe=red!75!black,
    coltitle=blue!50!black,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    title style tile={width=1cm}{pink_marble.png}]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}

The combined TikZ style applied to frame, interior, and title background can used by authors in customizing code.

  • /tikz/tcb fill lower bicolor(style, no value)New: 2025-07-07

    • This is a TikZ style which is finally applied to the interior lower part of the box, when the bicolor skin is used.

    Compiled output

    % \tcbuselibrary{hooks}
    % \usetikzlibrary{decorations.pathmorphing}
    \tcbset{bicolor,colback=red!5!white,
    colbacklower=blue!15!white,
    colframe=red!75!black,fonttitle=\bfseries,
    segmentation code app={
    \path[tcb fill lower bicolor,
    decoration={zigzag,amplitude=1mm}]
    decorate {
    ([yshift=-0.1pt]segmentation.east)
    --([yshift=-0.1pt]segmentation.west) }
    --cycle;} }

    \begin{tcolorbox}[title=My title]
    This is a \textbf{tcolorbox}.
    \tcblower
    This is the lower part.
    \end{tcolorbox}
10.2 Boxed Title Option Keys
10.2.1 Boxed Title Placement

The following options place the title text into an own \tcbox. This boxed title can be customized independently from the main box using /tcb/boxed title style. The placement can be influenced by ⟨boxtitle options⟩.

  • /tcb/attach boxed title to bottom text left={⟨boxtitle options⟩}(style, default empty)New: 2021-07-30

    • The title is boxed with a \tcbox and attached to the bottom left corner of the main box and shifted to match title text and box text. Note that this matches the upper part, even, if there is a lower part.

    Compiled output

    \begin{tcolorbox}[enhanced,title=My title,
    attach boxed title to bottom text left]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/attach boxed title to bottom text right={⟨boxtitle options⟩}(style, default empty)New: 2021-07-30

    • The title is boxed with a \tcbox and attached to the bottom right corner of the main box and shifted to match title text and box text. Note that this matches the upper part, even, if there is a lower part.

    Compiled output

    \begin{tcolorbox}[enhanced,title=My title,
    halign=right,
    attach boxed title to bottom text right]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/attach boxed title to top*={⟨boxtitle options⟩}(style, default empty)New: 2016-02-26

    • In contrast to /tcb/attach boxed title to top, this style uses smaller left and right rules to avoid previewer glitches. Typically, one would not use different colors for the frame as in the example below.

    Compiled output

    \begin{tcolorbox}[enhanced,title=My title,
    attach boxed title to top*,
    boxed title style={colframe=red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/attach boxed title to bottom*={⟨boxtitle options⟩}(style, default empty)New: 2016-02-26

    • In contrast to /tcb/attach boxed title to top, this style uses smaller left and right rules to avoid previewer glitches.

    Compiled output

    \begin{tcolorbox}[enhanced,title=My title,
    attach boxed title to bottom*]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}
10.2.2 Options for the Boxed Title Placement

The ⟨boxtitle options⟩ of the keys described above are shift values. The dimensions of the boxed title are stored into two macros \tcboxedtitleheight and \tcboxedtitlewidth. These macros can be used inside the following ⟨boxtitle options⟩:

The bounding box of the resulting total tcolorbox is adapted automatically to the vertical dimensions of the boxed title. Possible horizontal enlargements are not automatically computed.

Compiled output

\begin{tcolorbox}[enhanced,title=My title,
attach boxed title to top left=
{xshift=-2mm,yshift=-2mm},
boxed title style={size=small,colback=blue},
show bounding box]
This is a \textbf{tcolorbox}.
\end{tcolorbox}
10.2.3 Options for the Boxed Title Box

The boxed title options are implemented as an underlay, see Section 10.8. Therefore, a boxed title is not drawn, if a skin does not support underlays like standard. Still, the room for the boxed titles gets reserved in these cases.

A TikZ node title is produced by a boxed title which can be used inside /tcb/frame code, /tcb/interior code, underlays, overlays, and finishes.

A boxed title is almost always the first underlay. The only exceptions are underlays defined by /tcb/underlay boxed title which are drawn before. Additionally, underlays defined by /tcb/underlay boxed title are only drawn, if a boxed title is actually set. They are ignored, if there is no boxed title.

  • /tcb/no boxed title style(style, initially set)New: 2016-02-26

    • Removes all options which were set by /tcb/boxed title style.

  • /tcb/minipage boxed title*=⟨length⟩(initially unset)

    • The title text content is captured with a minipage with a width of main box width plus ⟨length⟩. By default, the resulting boxed title is somewhat smaller than the main box.

    Compiled output

    \newtcolorbox{mybox}[1]{minipage boxed title*=-2cm,
    enhanced,attach boxed title to top center=
    {yshift=-3mm,yshifttext=-1mm},
    boxed title style={size=small,colback=red},
    center title,title={#1}}

    \begin{mybox}{Short title}
    This is a \textbf{tcolorbox}.
    \end{mybox}\bigskip

    \begin{mybox}{This title is not really very short}
    This is a \textbf{tcolorbox}.
    \end{mybox}

  • /tcb/varwidth boxed title*=⟨length⟩(initially unset)

    • The title text content is captured with a varwidth environment with a width of main box width plus ⟨length⟩. This style needs the varwidth package [Arseneau 2011] to be loaded manually. By default, the resulting boxed title is somewhat smaller than the main box.

    Compiled output

    % \usepackage{varwidth}
    \newtcolorbox{mybox}[1]{varwidth boxed title*=-2cm,
    enhanced,attach boxed title to top center=
    {yshift=-3mm,yshifttext=-1mm},
    boxed title style={size=small,colback=red},
    center title,title={#1}}

    \begin{mybox}{Short title}
    This is a \textbf{tcolorbox}.
    \end{mybox}\bigskip

    \begin{mybox}{This title is not really very short}
    This is a \textbf{tcolorbox}.
    \end{mybox}
10.3 Watermark Option Keys

The skin standard does not support these watermarks, but all other skins, e. g. enhanced.

The watermark options rely on the more general overlay options described in Section 4.12. Therefore, watermarks and overlays cannot be used mixed. But a mixture is possible with the hooks library, see Section 23.

  • /tcb/watermark text on=⟨part⟩ is ⟨text⟩(no default, initially unset)

    • This option writes some ⟨text⟩ in the center of the interior region of a tcolorbox as described for /tcb/watermark text. But this is done only for boxes named ⟨part⟩ of a break sequence, see /tcb/breakable.
    Feasible values for ⟨part⟩ are:

    • broken: all broken box parts,

    • unbroken: unbroken boxes only,

    • first: first parts of a break sequence,

    • middle: middle parts of a break sequence,

    • last: last parts of a break sequence,

    • unbroken and first: unbroken boxes and first parts of a break sequence,

    • middle and last: middle and last parts of a break sequence.

    • first and middle: first and middle parts of a break sequence.

  • /tcb/watermark graphics on=⟨part⟩ is ⟨file name⟩(no default, initially unset)

    • This option draws a picture referenced by ⟨file name⟩ in the center of the interior region of a tcolorbox as described for /tcb/watermark graphics. But this is done only for boxes named ⟨part⟩ of a break sequence, see /tcb/breakable.
    Feasible values for ⟨part⟩ are:

    • broken: all broken box parts,

    • unbroken: unbroken boxes only,

    • first: first parts of a break sequence,

    • middle: middle parts of a break sequence,

    • last: last parts of a break sequence,

    • unbroken and first: unbroken boxes and first parts of a break sequence,

    • middle and last: middle and last parts of a break sequence.

  • /tcb/watermark tikz=⟨graphical code⟩(no default, initially unset)

    • Draws the given TikZ ⟨graphical code⟩ in the center of the interior region of a tcolorbox. The code is executed after the frame and interior are drawn and before the text content is drawn. The result is zoomed or stretched according the values of /tcb/watermark zoom or /tcb/watermark stretch.

    Compiled output

    \tcbset{colback=red!5!white,colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[enhanced,title=My title,
    watermark tikz={\draw[line width=2mm] circle (1cm)
    node{\fontfamily{ptm}\fontseries{b}\fontsize{20mm}{20mm}\selectfont ?};}]
    \lipsum[1]
    \tcblower
    \lipsum[2]
    \end{tcolorbox}

  • /tcb/watermark tikz on=⟨part⟩ is ⟨graphical code⟩(no default, initially unset)

    • This option draws the given TikZ ⟨graphical code⟩ in the center of the interior region of a tcolorbox as described for /tcb/watermark tikz. But this is done only for boxes named ⟨part⟩ of a break sequence, see /tcb/breakable.
    Feasible values for ⟨part⟩ are:

    • broken: all broken box parts,

    • unbroken: unbroken boxes only,

    • first: first parts of a break sequence,

    • middle: middle parts of a break sequence,

    • last: last parts of a break sequence,

    • unbroken and first: unbroken boxes and first parts of a break sequence,

    • middle and last: middle and last parts of a break sequence.

  • /tcb/no watermark(style, no default, initially set)

    • Removes the watermark if set before. This is an alias for /tcb/no overlay.

  • /tcb/watermark shrink=⟨fraction⟩(default 1, initially unset)Updated: 2022-07-21

    • Identically to /tcb/watermark zoom, but the watermark never gets enlarged. Thus, the watermark keeps its original size or is shrunk.

If a /tcb/watermark overzoom value of 1.0 is used in connection with invisible top and bottom rules which still have a thickness greater than 0pt, the space of these invisible rules may not be covered by the watermark. For example, this situation may occur during the breaking of /tcb/enhanced boxes. To avoid this optical glitch, just set /tcb/pad at break to any desired value.

Removing the clipping should be necessary only in very rare situations. Until version 5.1.1 (2022/06/24), theoretically, the watermark could be extended over the boundaries of the box without limit. Newer versions restrict the watermark to a box scaled 4 times the actual tcolorbox. If you really need to extend further, you are strongly advised to implement this by using /tcb/overlay or /tcb/underlay directly where no restrictions apply. Note that a watermark is just a special /tcb/overlay.

10.4 Clip Environments

The following clip environments are applicable for all skins which use engines of type path, pathfirst, pathmiddle, or pathlast. Especially, the skin enhanced supports all of them and standard none. The typical area of application is inside overlay code, see Section 4.12.

  • \begin{tcbinvclipframe}
    ⟨environment content⟩
    \end{tcbinvclipframe}

    • Defines a TikZ scope which clips to the outside of the frame area path.

    Compiled output

    \tcbset{enhanced jigsaw,fonttitle=\bfseries,opacityback=0.35,colback=blue!5!white,
    frame style={left color=red!75!black,right color=red!10!yellow}}

    \begin{tikzpicture}% draw two balls
    \path[use as bounding box] (0,0.8) rectangle +(0.1,0.1);
    \shadedraw [shading=ball] (0,0) circle (1cm);
    \shadedraw [ball color=red] (3,-2.2) circle (1cm);
    \end{tikzpicture}

    \begin{tcolorbox}[title=A translucent box,
    overlay={\begin{tcbinvclipframe}
    \draw[red,line width=1cm] ([xshift=-2mm,yshift=2mm]frame.north west)
    --([xshift=2mm,yshift=-2mm]frame.south east);
    \draw[red,line width=1cm] ([xshift=-2mm,yshift=-2mm]frame.south west)
    --([xshift=2mm,yshift=2mm]frame.north east);
    \end{tcbinvclipframe}}]
    \lipsum[2]
    \end{tcolorbox}

  • \begin{tcbclipinterior}
    ⟨environment content⟩
    \end{tcbclipinterior}

    • Defines a TikZ scope which clips to the interior area path.

    Compiled output

    \begin{tcolorbox}[enhanced,title=My Title,
    overlay={\begin{tcbclipinterior}
    \draw[red,line width=1cm] (interior.north west)--(interior.south east);
    \draw[red,line width=1cm] (interior.south west)--(interior.north east);
    \end{tcbclipinterior}}]
    \lipsum[1]
    \end{tcolorbox}

The example for /tcb/clip upper sizes the box according to the dimensions of the picture. To do it the other way around, the watermark options provide an easy solution.

Compiled output

\newcommand{\mygraphics}[2][]{%
\tcbox[enhanced,capture=minipage,boxsep=0pt,top=0pt,bottom=0pt,left=0pt,
right=0pt,boxrule=0.4pt,drop fuzzy shadow,nobeforeafter,
colback=black!75!white,toptitle=2pt,bottomtitle=2pt,
center title,fonttitle=\small\sffamily,title=\detokenize{#2},
width=(\linewidth-4mm)/2,height=6cm,colbacktitle={black},
watermark zoom=1.0,watermark graphics={#2}]{}}

\mygraphics{lichtspiel.jpg}\hfill
\mygraphics{Basilica_5.png}
10.5 Border Line Option Keys

The skin standard does not support these border lines, but most other skins, e. g. enhanced.

The borderlines are independent from the normal tcolorbox rules. They may be used with or without the /tcb/segmentation engine.

The borderlines are stackable, i. e., several different border lines can be used on the same tcolorbox. They are drawn after the box frame and box interior and before overlays or watermarks.

Technically, the normal tcolorbox rules result from a TikZ filling process. The border lines are created by a TikZ drawing process. This can be used to apply different effects.

  • /tcb/no borderline(no default, initially set)

    • Removes all borderlines if set before.

The following partial borderlines act slightly different from the complete borderlines described before. They ignore rounded corner settings, their length is not modified by their ⟨offset⟩, they ignore skin settings but adapt to breakable boxes.

  • /tcb/borderline north={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the north of the tcolorbox. A positive ⟨offset⟩ value moves the borderline inside the tcolorbox and a negative ⟨offset⟩ value moves it outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[enhanced,
    borderline north={2pt}{-2pt}{red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/borderline south={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the south of the tcolorbox. A positive ⟨offset⟩ value moves the borderline inside the tcolorbox and a negative ⟨offset⟩ value moves it outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[enhanced,
    borderline south={2pt}{-2pt}{red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/borderline east={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the east of the tcolorbox. A positive ⟨offset⟩ value moves the borderline inside the tcolorbox and a negative ⟨offset⟩ value moves it outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[enhanced,
    borderline east={2pt}{-2pt}{red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/borderline west={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the west of the tcolorbox. A positive ⟨offset⟩ value moves the borderline inside the tcolorbox and a negative ⟨offset⟩ value moves it outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[enhanced,
    borderline west={2pt}{-2pt}{red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/borderline horizontal={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the north and south of the tcolorbox. A positive ⟨offset⟩ value moves the borderlines inside the tcolorbox and a negative ⟨offset⟩ value moves them outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[blanker,top=3mm,bottom=3mm,
    borderline horizontal={2pt}{0pt}{red}]
    This is a \textbf{tcolorbox}.
    \end{tcolorbox}

  • /tcb/borderline vertical={⟨width⟩}{⟨offset⟩}{⟨options⟩}(no default, initially unset)New: 2014-10-20

    • Adds a new borderline with the given ⟨width⟩ to the east and west of the tcolorbox. A positive ⟨offset⟩ value moves the borderlines inside the tcolorbox and a negative ⟨offset⟩ value moves them outside without changing the bounding box.

    Compiled output

    \begin{tcolorbox}[blanker,left=3mm,right=3mm,
    borderline vertical={2pt}{0pt}{red}]
    This is a \textbf{tcolorbox}.\\
    My second line.
    \end{tcolorbox}

Compiled output

\begin{tcolorbox}[enhanced,colback=yellow!10!white,boxrule=0pt,frame hidden,
borderline north={1mm}{-2mm}{red},
borderline south={1mm}{-2mm}{blue},
borderline west={1mm}{-2mm}{green},
borderline east={1mm}{-2mm}{yellow}]
\lipsum[1]
\end{tcolorbox}
10.6 Shadow Option Keys

The skin standard does not support these shadows, but most other skins, e. g. enhanced.

The shadows are stackable, i. e., several different shadows can be used on the same tcolorbox. They are drawn before the box frame is drawn.

  • /tcb/no shadow(no default)

    • Removes all shadows if set before.

10.6.1 Common Shadows and Halos

For all following shadows, the optionally given ⟨color⟩ for the shadow can be changed equivalent to the preceding examples.

10.6.2 Lifted Shadows
10.6.3 Generic Shadows

  • /tcb/shadow={⟨xshift⟩}{⟨yshift⟩}{⟨offset⟩}{⟨options⟩}(no default)

    • Adds a new shadow to the stack of shadows. This shadow follows the outline of the tcolorbox but is shifted by ⟨xshift⟩ and ⟨yshift⟩. The ⟨offset⟩ value is a distance value from the frame outline. A positive ⟨offset⟩ value shrinks the shadow and a negative ⟨offset⟩ value enlarges the shadow. The shadow is filled along a TikZ path with the given TikZ ⟨options⟩.
    The shadows adapt to the rounded corners of the tcolorbox. A shrunken shadow will switch to sharp corners if necessary, an enlarged shadow may become more rounded depending on several factors. But /tcb/sharp corners have sharp shadows.

    Shadows are not considered for the bounding box computation by default. Large shadows may be overlapped by the following content. But, the bounding box can be adapted if necessary.

    Compiled output

    \tcbset{enhanced,colback=red!5!white,
    colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[title=My own shadow,
    shadow={2mm}{-1mm}{0mm}{black!50!white}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Another shadow,
    shadow={-1mm}{-2mm}{0mm}{fill=blue,
    opacity=0.5}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Double shadow,
    shadow={-1.5mm}{-1.5mm}{0mm}{fill=blue,
    opacity=0.25},
    shadow={1.5mm}{-1.5mm}{0mm}{fill=red,
    opacity=0.25}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Far shadow,
    shadow={5.5mm}{-3.5mm}{2mm}{fill=black,
    opacity=0.25}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip\bigskip
    \begin{tcolorbox}[title=Halo shadow,
    shadow={0mm}{0mm}{-1.5mm}%
    {fill=yellow!75!red,opacity=0.5}]
    This is a tcolorbox.
    \end{tcolorbox}

  • /tcb/fuzzy shadow={⟨xshift⟩}{⟨yshift⟩}{⟨offset⟩}{⟨step⟩}{⟨options⟩}(no default)

    • Adds a new fuzzy shadow to the stack of shadows. Actually, this option adds several shadows which appear like a shadow with a fuzzy border. This fuzzy shadow follows the outline of the tcolorbox but is shifted by ⟨xshift⟩ and ⟨yshift⟩. The ⟨offset⟩ value is a distance value from the frame outline. A positive ⟨offset⟩ value shrinks the shadow and a negative ⟨offset⟩ value enlarges the shadow. The {⟨step⟩} value describes a shrink offset used for the combination of the partial shadows. The shadow is filled along a TikZ path with the given TikZ ⟨options⟩ but any opacity value will be ignored.

    Compiled output

    \tcbset{enhanced,colback=red!5!white,
    colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[title=My own shadow,
    fuzzy shadow={2mm}{-1mm}{0mm}{0.1mm}%
    {black!50!white}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Another shadow,
    fuzzy shadow={-1mm}{-2mm}{0mm}{0.2mm}%
    {fill=blue}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Double shadow,
    fuzzy shadow={-1.5mm}{-1.5mm}{0mm}{0.1mm}%
    {blue},
    fuzzy shadow={1.5mm}{-1.5mm}{0mm}{0.1mm}%
    {red}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip
    \begin{tcolorbox}[title=Far shadow,
    fuzzy shadow={5.5mm}{-3.5mm}{0mm}{0.3mm}%
    {black}]
    This is a tcolorbox.
    \end{tcolorbox}
    \par\bigskip\bigskip
    \begin{tcolorbox}[title=Glow shadow,
    fuzzy shadow={0mm}{0mm}{-1.5mm}{0.15mm}%
    {yellow!75!red}]
    This is a tcolorbox.
    \end{tcolorbox}

    Compiled output

    \newtcolorbox{mybox}[1][]{enhanced,
    fuzzy shadow={1.0mm}{-1.0mm}{0.12mm}{0mm}{blue!50!white},
    fuzzy shadow={-1.0mm}{-1.0mm}{0.12mm}{0mm}{red!50!white},
    fuzzy shadow={-1.0mm}{1.0mm}{0.12mm}{0mm}{green!50!white},
    fuzzy shadow={1.0mm}{1.0mm}{0.12mm}{0mm}{yellow!50!white},#1
    }

    \begin{mybox}[title=A multi shadow box]
    This is a tcolorbox.
    \end{mybox}

  • /tcb/lifted shadow={⟨xshift⟩}{⟨yshift⟩}{⟨bend⟩}{⟨step⟩}{⟨options⟩}(no default)

    • Adds a new lifted shadow to the stack of shadows. Actually, this option adds several shadows which appear like a shadow with a fuzzy border. This lifted shadow follows the outline of the tcolorbox but is shifted by ⟨xshift⟩ and ⟨yshift⟩ on the lower left corner and by \(-\)⟨xshift⟩ and ⟨yshift⟩ on the lower right corner. Additionally, there is a ⟨bend⟩ in the middle. The {⟨step⟩} value describes a shrink offset used for the combination of the partial shadows. The shadow is filled along a TikZ path with the given TikZ ⟨options⟩ but any opacity value will be ignored.

    Compiled output

    \tcbset{enhanced,colback=red!5!white,
    boxrule=0.1pt,
    colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[title=My own shadow,
    lifted shadow={1mm}{-2mm}{3mm}{0.1mm}%
    {black!50!white}]
    This is a tcolorbox.
    \end{tcolorbox}
10.6.4 TikZ Shadows

Alternative to the package shadow options described before, shadows from the «Shadows Library» of TikZ can be used. Such shadows can be added directly to the frame path using /tcb/frame style.

Compiled output

% \usetikzlibrary{shadows}
\begin{tcolorbox}[enhanced,
colback=red!5!white,colframe=red!75!black,
frame style={drop shadow} ]
This is a tcolorbox.
\end{tcolorbox}

Compiled output

% \usetikzlibrary{shadows}
\begin{tcolorbox}[enhanced,height=3cm,
colback=red!5!white,colframe=red!75!black,
halign=center,valign=center,
frame style={circular drop shadow} ]
This is a tcolorbox.
\end{tcolorbox}

Compiled output

% \usetikzlibrary{shadows}
\begin{tcolorbox}[enhanced,width=2.5cm,
square,circular arc,
halign=center,valign=center,
colback=red!5!white,colframe=red!75!black,
frame style={circular glow={fill=red}} ]
tcolorbox
\end{tcolorbox}
10.7 TikZ Picture Option Keys

  • /tcb/tikz reset(initially set)

    • Removes all options given by /tcb/tikz.

  • /tcb/at begin tikz=⟨tikz code⟩(no default, initially empty)

    • The given ⟨tikz code⟩ is executed at the beginning of the tikzpicture environment after the TikZ option execute at begin picture was applied. If this option is applied a second time, the new ⟨tikz code⟩ is appended to the current code.

  • /tcb/at end tikz=⟨tikz code⟩(no default, initially empty)

    • The given ⟨tikz code⟩ is executed at the ending of the tikzpicture environment before the TikZ option execute at end picture was applied. If this option is applied a second time, the new ⟨tikz code⟩ is appended to the current code.

  • /tcb/rotate=⟨angle⟩(no default, initially unset)

    • Rotates the tcolorbox by the given ⟨angle⟩. This also applys transform shape. Note that this is a TikZ coordinate transformation i. e., not all graphical elements like shadings will really be rotated.

    Compiled output

    \tcbset{enhanced,colback=red!5!white,
    colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[title=Rotated box,rotate=30]
    This is a tcolorbox.
    \end{tcolorbox}

  • /tcb/scale=⟨fraction⟩(no default, initially unset)

    • Scales the tcolorbox by the given ⟨fraction⟩. This also applys transform shape. Note that this is a TikZ coordinate transformation i. e., not all graphical elements like line widths will really be scaled.

    Compiled output

    \tcbset{enhanced,colback=red!5!white,
    colframe=red!75!black,fonttitle=\bfseries}

    \begin{tcolorbox}[title=Scaled box,scale=0.5]
    This is a tcolorbox.
    \end{tcolorbox}
    \begin{tcolorbox}[title=Scaled box,scale=1.25]
    This is a tcolorbox.
    \end{tcolorbox}

  • /tcb/remember(style, initially unset)

    • Shortcut for tikz={remember picture}. This allows one to reference nodes in other TikZ pictures.

    Compiled output

    \begin{tcolorbox}[enhanced,remember,colback=red!5!white,colframe=red!75!black,
    fonttitle=\bfseries,title=The four corners of a paper,
    overlay={\draw[red!50!white,line width=1mm,opacity=0.5,shorten >=3mm]
    (frame.north west) edge[->] (current page.north west)
    (frame.north east) edge[->] (current page.north east)
    (frame.south west) edge[->] (current page.south west)
    (frame.south east) edge[->] (current page.south east);}]
    This is a tcolorbox.
    \end{tcolorbox}

  • /tcb/remember as=⟨name⟩(style, no default, initially unset)

    • The frame node will be remembered by the given ⟨name⟩ to be referenced in other TikZ pictures.

    Compiled output

    % \usepackage{lipsum}
    \newtcolorbox{mybox}[1][]{enhanced,colframe=blue!75!black,colback=blue!10!white,
    fonttitle=\bfseries,#1}

    \begin{mybox}[title=First Box,nobeforeafter,width=\linewidth/4,remember as=one]
    This is a test.
    \end{mybox}
    \hfill
    \begin{mybox}[title=Second Box,nobeforeafter,width=\linewidth/4,remember as=two]
    This is a test.
    \end{mybox}
    \hfill
    \begin{mybox}[title=Third Box,nobeforeafter,width=\linewidth/4,remember as=three]
    This is a test.
    \end{mybox}

    \lipsum[2]

    \begin{mybox}[title=Fourth Box,remember as=four]
    This is a test.
    \end{mybox}

    \begin{tikzpicture}[overlay,remember picture,line width=1mm,draw=red!75!black]
    \draw[->] (one.east) to[bend right] node[above] {A} (two.west);
    \draw[->] (two.east) to[bend left] node[above] {B} (three.west);
    \draw[->] (three.east) to[bend left=90] node[right] {C} (four.east);
    \draw[->] (four.west) to[bend left=90] node[left] {D} (one.west);
    \end{tikzpicture}
10.8 Underlay Option Keys

Underlays are quite similar to overlays described in Section 4.12. Underlays are drawn after the frame and interior are drawn and before overlays and the text content is drawn; see Section 9.4 for the general drawing scheme.

The differences between underlays and overlays are:

  • Underlays are not applicable for the skins standard and standard jigsaw, whereas overlays are applicable also for these skins. The skin spartan supports underlays but no overlays.

    If an underlay is used with the standard skin, it is silently ignored.

  • Underlays are stackable, i. e., several different underlays can be used on the same tcolorbox. Overlays are not stackable by default (but with some help of the library hooks).

  • Boxed titles are implemented with underlays (Section 10.2), watermarks are implemented with overlays (Section 10.3).

  • /tcb/no underlay(style, no default, initially set)

    • Removes the underlay if set before.

  • /tcb/underlay broken=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process. /tcb/underlay overwrites this key.

  • /tcb/underlay unbroken=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable but is not broken actually or if the box is set to be /tcb/unbreakable, then the ⟨graphical code⟩ is added to the box drawing process. /tcb/underlay overwrites this key.

  • /tcb/no underlay unbroken(style, no default, initially set)

    • Removes the unbroken underlay if set before.

  • /tcb/underlay first=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the first part of the break sequence. /tcb/underlay overwrites this key.

  • /tcb/no underlay first(style, no default, initially set)

    • Removes the first underlay if set before.

  • /tcb/underlay middle=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the middle parts (if any) of the break sequence. /tcb/underlay overwrites this key.

  • /tcb/no underlay middle(style, no default, initially set)

    • Removes the middle underlay if set before.

  • /tcb/underlay last=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the last part of the break sequence. /tcb/underlay overwrites this key.

  • /tcb/no underlay last(style, no default, initially set)

    • Removes the last underlay if set before.

  • /tcb/underlay boxed title=⟨graphical code⟩(no default, initially unset)

    • If the box has a boxed title, see Section 10.2, then the ⟨graphical code⟩ is added to the box drawing process before the boxed title is drawn.

  • /tcb/no underlay boxed title(style, no default, initially set)

    • Removes the boxed title underlay if set before.

10.9 Finish Option Keys

Finishes are quite similar to underlays described in Section 10.8 and overlays described in Section 4.12. Finishes are drawn after the text content is drawn; see Section 9.4 for the general drawing scheme. Therefore, a finish will reduce the readability of the text content.

Finishes are intended for special effects like highlights or glosses or text over text.

  • Finishes are only applicable for the skins enhanced, empty, freelance, bicolor, beamer, and widget.

    If a finish is used with the standard skin, it is silently ignored.

  • Finishes are stackable, i. e., several different finishes can be used on the same tcolorbox.

  • /tcb/finish=⟨graphical code⟩(no default, initially unset)

    • Adds ⟨graphical code⟩ to the box drawing process. This ⟨graphical code⟩ is drawn after the text content.

    Compiled output

    \newtcolorbox{mybox}[1][]{enhanced,colback=red!5!white,
    colbacktitle=red!85!black!50!white,colframe=red!75!black,fonttitle=\bfseries,
    finish={\begin{tcbclipframe}
    \path[bottom color=black,top color=black!50!white,opacity=0.1]
    (frame.south west) -- (frame.south east) -- (frame.north east) -- cycle;
    \path[top color=white,bottom color=black!50!white,opacity=0.1]
    (frame.south west) -- (frame.north east) -- (frame.north west) -- cycle;
    \end{tcbclipframe}},#1}

    \begin{mybox}[title=My box]
    \lipsum[2]
    \end{mybox}

    Compiled output

    \newtcolorbox{mybox}[1][]{enhanced,colback=red!5!white,
    colbacktitle=red!85!black!50!white,colframe=red!75!black,fonttitle=\bfseries,
    finish={\node[draw,fill=white,fill opacity=0.85,inner sep=5mm,
    rounded corners] at (frame.center) {\Huge\bfseries Finish!};},#1}

    \begin{mybox}[title=My box]
    \lipsum[2]
    \end{mybox}

  • /tcb/no finish(style, no default, initially set)

    • Removes the finish if set before.

  • /tcb/finish broken=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process. /tcb/finish overwrites this key.

  • /tcb/finish unbroken=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable but is not broken actually or if the box is set to be /tcb/unbreakable, then the ⟨graphical code⟩ is added to the box drawing process. /tcb/finish overwrites this key.

  • /tcb/no finish unbroken(style, no default, initially set)

    • Removes the unbroken finish if set before.

  • /tcb/finish first=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the first part of the break sequence. /tcb/finish overwrites this key.

  • /tcb/no finish first(style, no default, initially set)

    • Removes the first finish if set before.

  • /tcb/finish middle=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the middle parts (if any) of the break sequence. /tcb/finish overwrites this key.

  • /tcb/no finish middle(style, no default, initially set)

    • Removes the middle finish if set before.

  • /tcb/finish last=⟨graphical code⟩(no default, initially unset)

    • If the box is set to be /tcb/breakable and is broken actually, then the ⟨graphical code⟩ is added to the box drawing process for the last part of the break sequence. /tcb/finish overwrites this key.

  • /tcb/no finish last(style, no default, initially set)

    • Removes the last finish if set before.

10.10 Hyper Option Keys

All options of this section need the package hyperref [Rahtz and Oberdiek 2025] to be loaded separately. All these options are implemented as /tcb/finish and can be disabled by /tcb/no finish.

If the package hyperref [Rahtz and Oberdiek 2025] is not loaded or if the standard skin is used, all hyper option are silently ignored.

  • /tcb/hyperref=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • The whole frame of a tcolorbox is made an active hyperlink for a ⟨marker⟩ which was given by \label or /tcb/label or /tcb/phantomlabel. Such, the tcolorbox is made a clickable button (depending on the previewer).

    Compiled output

    % \section{Library skins}\label{sec:skins}%
    \begin{tcolorbox}[beamer,colback=red!50,
    hyperref=sec:skins]
    Jump to the heading of Section~\ref*{sec:skins}.
    \end{tcolorbox}

  • /tcb/hyperref interior=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperref, but only the interior of a tcolorbox is made a hyperlink (without frame and title).

  • /tcb/hyperref title=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperref, but only the title of a tcolorbox is made a hyperlink.

  • /tcb/hyperref node={⟨marker⟩}{⟨node⟩}(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperref, but only the given TikZ ⟨node⟩ is made a hyperlink. This ⟨node⟩ may be frame, interior, title, or any other named node used for drawing the tcolorbox. The ⟨node⟩ may be defined inside /tcb/underlay, /tcb/overlay or /tcb/finish. If the later is used, define the node before /tcb/hyperref node is applied.

    Compiled output

    % \section{Library skins}\label{sec:skins}%
    \begin{tcolorbox}[enhanced,colback=yellow!10,
    underlay={\node[red,fill=red!30,inner sep=3mm]
    (click) at (frame.center) {X};},
    hyperref node={sec:skins}{click}]
    Jump to the heading of Section~\ref*{sec:skins}
    (X marks the click point).
    \end{tcolorbox}

  • /tcb/hyperlink=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • The whole frame of a tcolorbox is made an active hyperlink for a ⟨marker⟩ which was given by \hypertarget or /tcb/hypertarget. Such, the tcolorbox is made a clickable button (depending on the previewer).

    Compiled output

    % \usepackage{hyperref}%
    \begin{tcolorbox}[enhanced,
    colback=blue!10,colframe=blue!50!black,
    hypertarget=hypertwinB,
    hyperlink=hypertwinA,
    title=Box B]
    Click me to jump to Box A.
    \end{tcolorbox}

  • /tcb/hyperlink interior=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperlink, but only the interior of a tcolorbox is made a hyperlink (without frame and title).

  • /tcb/hyperlink title=⟨marker⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperlink, but only the title of a tcolorbox is made a hyperlink.

  • /tcb/hyperlink node={⟨marker⟩}{⟨node⟩}(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperlink, but only the given TikZ ⟨node⟩ is made a hyperlink. This ⟨node⟩ may be frame, interior, title, or any other named node used for drawing the tcolorbox. The ⟨node⟩ may be defined inside /tcb/underlay, /tcb/overlay or /tcb/finish. If the later is used, define the node before /tcb/hyperlink node is applied.

  • /tcb/hyperurl=⟨url⟩(no default, initially unset)New: 2017-02-03

    • The whole frame of a tcolorbox is made an active hyperlink for a ⟨url⟩ in the same manner as using \href or \url. Such, the tcolorbox is made a clickable button (depending on the previewer).

    Compiled output

    \begin{tcolorbox}[enhanced,colback=red!50,
    hyperurl=https://www.ctan.org/pkg/tcolorbox]
    View CTAN with a browser.
    \end{tcolorbox}

  • /tcb/hyperurl interior=⟨url⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperurl, but only the interior of a tcolorbox is made a hyperlink (without frame and title).

  • /tcb/hyperurl title=⟨url⟩(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperurl, but only the title of a tcolorbox is made a hyperlink.

  • /tcb/hyperurl node={⟨url⟩}{⟨node⟩}(no default, initially unset)New: 2017-02-03

    • Identical to /tcb/hyperurl, but only the given TikZ ⟨node⟩ is made a hyperlink. This ⟨node⟩ may be frame, interior, title, or any other named node used for drawing the tcolorbox. The ⟨node⟩ may be defined inside /tcb/underlay, /tcb/overlay or /tcb/finish. If the later is used, define the node before /tcb/hyperurl node is applied.

10.11 Jigsaw Skin Variants

As described in Section 9.1, a tcolorbox is drawn by up to four engines. Typically, the frame engine fills the complete box area with color and the other engines fill certain areas with other colors. Finally, only the area which you see as frame of the box will display the frame color. For most applications, this is a good approach.

For certain boxes, a more delicate procedure is needed. E. g., if the box should be translucent, an already painted area cannot be made unpainted. Therefore, more elaborate frame engines saw holes into the frame where the interior area and optionally the title area will be painted. The resulting skins are called jigsaw skins. For standard, enhanced, and bicolor, there are variants called standard jigsaw, enhanced jigsaw, and bicolor jigsaw.

Compiled output

\newcommand{\ballexample}{\begin{tikzpicture}
\path[use as bounding box] (0,0.8) rectangle +(0.1,0.1);
\shadedraw [shading=ball] (0,0) circle (1cm);
\shadedraw [ball color=red] (3,-2.2) circle (1cm);
\end{tikzpicture}}

\tcbset{enhanced,colback=blue!5!white,
frame style={left color=red!75!black,right color=red!10!yellow},
fonttitle=\bfseries }

\ballexample

\begin{tcolorbox}[title=A normal box]
\lipsum[2]
\end{tcolorbox}

\ballexample

\begin{tcolorbox}[title=A translucent jigsaw box,
enhanced jigsaw,opacityback=0.35]
\lipsum[2]
\end{tcolorbox}

Compiled output

\tcbset{enhanced,colback=red!10!white,coltitle=black,
frame style={left color=red!75!black,right color=red!10!yellow},
fonttitle=\bfseries,interior hidden,title hidden}

\begin{tcolorbox}[title=A normal box with hidden interior and title]
This is a tcolorbox.
\end{tcolorbox}

\begin{tcolorbox}[enhanced jigsaw,
title=A jigsaw box with hidden interior and title]
This is a tcolorbox.
\end{tcolorbox}

Compiled output

\newtcolorbox{mybox}{skin=enhancedmiddle jigsaw,leftrule=5mm,rightrule=5mm,
boxsep=0mm,top=0mm,bottom=0mm,
frame style={top color=blue,bottom color=red},interior hidden}

\begin{mybox}
\lipsum[2]
\end{mybox}
10.12 Draft Mode

To reduce the compilation time while drafting a document, the draft mode can be applied. Basically, it changes all skins to spartan and sets the /tcb/fit algorithm to squeeze. Especially, when fuzzy shadows are used, the speedup will be considerable high.

It is strongly recommended that the draft mode is not used for the final document. Use spartan directly, if you want to stay with it. The draft mode implementation may change in future.

Normally, switching to the draft mode should not alter the geometry of your document. Since overlays are deactivated, any code placed there (e. g. counter changes) is not executed anymore! Also, /tcb/remember as will not have any effect. You may exclude critical code with \tcbinterruptdraftmode / \tcbcontinuedraftmode from converting to draft mode.

  • \tcbstartdraftmode

    • Any following tcolorbox code is put into draft mode. All skin settings are overruled with spartan. Overlays, watermarks, shadows, borderlines, and rounded corners are deactivated for all tcolorbox layers.

  • \tcbstopdraftmode

    • The draft mode is deactivated for the following code.

  • \tcbinterruptdraftmode

    • If the compilation is in draft mode, the draft mode is deactivated until a following \tcbcontinuedraftmode is detected. If the compilation is not in draft mode, nothing happens and a following \tcbcontinuedraftmode will not start the draft mode.

    The pair \tcbinterruptdraftmode and \tcbcontinuedraftmode cannot be used nested.

  • /tcb/draftmode=true|false(default true, initially false)

    • If set to true, the draft mode is started. If set to false, the draft mode is stopped.

    Compiled output

    \newtcolorbox{mybeamer}[2][]{beamer,colback=Salmon!50!white,
    colframe=FireBrick!75!black,adjusted title={#2},#1}

    \begin{mybeamer}{Beamer box}
    This box looks like a box provided by the \texttt{beamer} class.
    \end{mybeamer}\par\medskip
    \begin{mybeamer}[draftmode]{Beamer box}
    This box looks like a box provided by the \texttt{beamer} class.
    \end{mybeamer}