% !TeX root = tcolorbox.tex
% include file of tcolorbox.tex (manual of the LaTeX package tcolorbox)
\clearpage
\section{Initialization Option Keys}\label{sec:initkeys}%
\tcbset{external/prefix=external/initoptions_}%
The \emph{initialization} options are only applicable for the generation
of new environments and commands based on |tcolorbox| and friends.
Particularly, they can be used for
\begin{itemize}
\item\refCom{newtcolorbox}, \refCom{NewTColorBox}, \refCom{NewTotalTColorBox},
\item\refCom{newtcbox}, \refCom{NewTCBox}, \refCom{NewTotalTCBox},
\item\refCom{newtcblisting}, \refCom{NewTCBListing},
\item\refCom{newtcbinputlisting}, \refCom{NewTCBInputListing},
\item\refCom{newtcbtheorem}, \refCom{NewTcbTheorem},
\item\refCom{newtcboxfit}, \refCom{NewTCBoxFit}, \refCom{NewTotalTCBoxFit},
\end{itemize}
and friends like \refCom{renewtcolorbox}, etc.

\bigskip
\begin{marker}
Typically, these options may generate counters and alike.
It is \textbf{strongly} recommended that you use initialization options inside
the preamble only. Otherwise, you may get trouble when using \LaTeX's |\include| features.
Also, it is recommended to generate new environments and commands with these
options \emph{after} |hyperref| is loaded to avoid warnings about
\emph{duplicate identifiers}.
\end{marker}


\subsection{Numbered Boxes}\label{sec:numberedboxes}
Counters assigned using the initialization options are administrated
automatically. Especially, they are increased for each new box.

\begin{docCommand}{thetcbcounter}{}
Counter value of the current numbered box. It may be used inside the box,
e.\,g.\ inside the title of
the box. See \refKey{/tcb/new/auto counter} and following for examples.
\end{docCommand}

\begin{docCommand}{tcbcounter}{}
Real counter name of the current numbered box for possible use inside the box.
\end{docCommand}

\begin{docCommand}[doc new=2025-07-21]{thetcbcounterof}{\marg{tcolorbox}}
Counter value of a numbered \meta{tcolorbox} created with
initialization options as documented below, e.\,g.\ \refKey{/tcb/new/auto counter}.
\meta{tcolorbox} can be the name of a created box environment (by \refCom{newtcolorbox} and friends)
or a created box macro (by \refCom{newtcbox} and friends; here, the name is
without the leading backslash of the macro).
\end{docCommand}

\begin{docCommand}[doc new=2025-07-21]{tcbcounterof}{\marg{tcolorbox}}
Real counter name of a numbered \meta{tcolorbox}.
\end{docCommand}


\clearpage
\begin{newTcbKey}{auto counter}{}{no value, initially unset}
Creates a new counter automatically.
With \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within}, the appearance and behavior of the counter
can be changed. The counter value is referenced by \refCom{thetcbcounter}.

\inputpreamblelisting{A}

\begin{dispExample}
\begin{pabox}[label={myautocounter}]{Title with number}
This box is automatically numbered with \ref{myautocounter} on page
\pageref{myautocounter}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{pabox}
\end{dispExample}
\end{newTcbKey}


\begin{newTcbKey}{use counter from}{=\meta{tcolorbox}}{no default, initially unset}
Here, a counter from another \meta{tcolorbox} is reused.
Note that the settings for \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within} are inherited and cannot be changed.
The counter value is referenced by \refCom{thetcbcounter}.

\begin{dispExample}
\newtcolorbox[use counter from=pabox]{mybox}[2][]{%
colback=blue!5!white,colframe=blue!75!black,fonttitle=\bfseries,
title=Some Box \thetcbcounter: #2,#1}

\begin{mybox}[label={myusecounterfrom}]{Title with continued number}
This box is automatically numbered with \ref{myusecounterfrom} on page
\pageref{myusecounterfrom}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{mybox}
\end{dispExample}
\end{newTcbKey}


\clearpage
\begin{newTcbKey}{use counter}{=\meta{counter}}{no default, initially unset}
Here, an ordinary existing \LaTeX\ \meta{counter} is used for numbering.
With \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within}, the appearance and behavior of the counter
can be changed. The counter value is referenced by \refCom{thetcbcounter}.

\begin{dispExample}
% \newcounter{myexample}%  preamble
\newtcolorbox[use counter=myexample,number format=\Alph]{mybox}[2][]{%
colback=green!5!white,colframe=green!55!black,fonttitle=\bfseries,
title=Some Box \thetcbcounter: #2,#1}

\begin{mybox}[label={myusecounter}]{Title with \LaTeX\ number}
This box is automatically numbered with \ref{myusecounter} on page
\pageref{myusecounter}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{mybox}
\end{dispExample}
\end{newTcbKey}


\begin{newTcbKey}[][doc new=2014-09-19]{use counter*}{=\meta{counter}}{no default, initially unset}
An existing \LaTeX\ \meta{counter} is used for numbering. In contrast to
\refKey{/tcb/new/use counter}, the options \refKey{/tcb/new/number format} and
\refKey{/tcb/new/number within} are ignored. Use this for counters which
are already configured outside the |tcolorbox| package, e.\,g.\ the standard
|figure| counter.
\end{newTcbKey}


\begin{newTcbKey}{no counter}{}{no value, initially set}
The created boxes are not numbered. This is the default. The option may
be used to overrule a previous option.
\end{newTcbKey}


\begin{newTcbKey}[][doc new=2019-10-18]{reset counter on overlays}{\colOpt{=true\textbar false}}{default |true|, initially |false|}
For |beamer| slides, this invokes the |\resetcounteronoverlays| command
for the box counter. The counter is automatically reset on subsequent
overlay slides of a frame.
Thereby, the counter will be the same on all slides of every frame.
\end{newTcbKey}


\clearpage
\begin{newTcbKey}{number within}{=\meta{counter}}{no default, initially unset}
The automatic counter is set to zero, if \meta{counter} is increased.
Additionally, during output, the value of \meta{counter} is prepended to the value of
the automatic counter.\par
To prepend the automatic counter with the chapter number and to reset it
with every new chapter, use:
\begin{dispListing}
number within=chapter
\end{dispListing}
See \refKey{/tcb/new/use counter} for a complete example.
\end{newTcbKey}


\begin{newTcbKey}[][doc new=2025-07-21]{number within from}{=\meta{tcolorbox}}{no default, initially unset}
This is a shortcut for \refKey{/tcb/new/number within}|=|\refCom{tcbcounterof}\meta{tcolorbox},
i.\,e.\ the automatic counter is set to zero, if the counter of the referenced \meta{tcolorbox} is increased.
\end{newTcbKey}


\begin{newTcbKey}{number format}{=\meta{format macro}}{no default, initially \texttt{\textbackslash arabic}}
Declares the format of the automatic counter. The \meta{format macro} can be
any valid \LaTeX\ number formatting macro like |\arabic|, |\roman|, etc.\par
To display the counter value in large roman numbers, use:
\begin{dispListing}
number format=\Roman
\end{dispListing}
See \refKey{/tcb/new/auto counter} for a complete example.
\end{newTcbKey}


\begin{newTcbKey}{number freestyle}{=\meta{code}}{no default, initially unset}
Allows advanced control over the complete number format. This option overrules
the format given by \refKey{/tcb/new/number within} and \refKey{/tcb/new/number format}.
Nevertheless, you can combine it with \refKey{/tcb/new/number within} to
get the desired reset property.\par
The \meta{code} is some formatting code which should contain \refCom{tcbcounter} to
reference the automated counter. Since this \meta{code} is expanded, you have
to secure each macro with |\noexpand| with \emph{exception} of \refCom{tcbcounter}.

\inputpreamblelisting{H}

\begin{dispExample}
\begin{phbox}[label={myfreestyle}]{Title with freestyle number}
This box is automatically numbered with \ref{myfreestyle} on page
\pageref{myfreestyle}. Inside the box, the \thetcbcounter\ can
also be referenced by |\thetcbcounter|.
The real counter name is \texttt{\tcbcounter}.
\end{phbox}
\end{dispExample}
\end{newTcbKey}

\clearpage
\begin{marker}
The following options \refKey{/tcb/new/crefname} and \refKey{/tcb/new/Crefname}
need to be set inside the preamble.
Note that \refPkg{cleveref} had its last update in 2018 (as of 2025-06-04) and
had or has conflicts with recent \LaTeX\ kernels. \refPkg{zref-clever} is
a possible alternative.
\end{marker}

\begin{newTcbKey}[][doc updated=2014-12-01]{crefname}{=\marg{singular}\marg{plural}}{no default, initially unset}
  This option key can be used only in conjunction with the \refPkg{cleveref} package
  \cite{cubitt:2018a} which has to be loaded separately.
  It creates a cross-reference type for the new |tcolorbox|'es, where the
  lowercase \meta{singular} and \meta{plural} forms of the cross-reference are given.
  This type is the environment or macro name and \refKey{/tcb/label type} is set automatically.
  See \refKey{/tcb/label type} and \cite{cubitt:2018a} for more information.
\end{newTcbKey}


\begin{newTcbKey}[][doc updated=2014-12-01]{Crefname}{=\marg{singular}\marg{plural}}{no default, initially unset}
  This option key can be used only in conjunction with the \refPkg{cleveref} package
  \cite{cubitt:2018a} which has to be loaded separately.
  It creates a cross-reference type for the new |tcolorbox|'es, where the
  uppercase \meta{singular} and \meta{plural} forms of the cross-reference are given.
  This type is the environment or macro name and \refKey{/tcb/label type} is set automatically.
  See \refKey{/tcb/label type} and \cite{cubitt:2018a} for more information.
\end{newTcbKey}

\begin{fulldocumentlisting}{
  comment style={raster columns=1,raster left skip=20mm,raster right skip=20mm},
  run pdflatex}
\documentclass[12pt]{article}
\usepackage[papersize={160mm,80mm},noheadfoot,margin=10mm]{geometry}
\usepackage{varioref,cleveref}
\usepackage{tcolorbox}

\newtcolorbox[auto counter,number within=section,
  crefname={bluebox}{blueboxes}]%
  {mybluebox}[2][]{colback=blue!5!white,colframe=blue!75!black,fonttitle=\bfseries,
     title=Bluebox \thetcbcounter: #2,#1}

\begin{document}
\section{Blue}

\begin{mybluebox}[label={myreference}]{My title}
This is an example.
\end{mybluebox}

\noindent\Cref{myreference}, \cref{myreference}.\\
\Cpageref{myreference}, \cpageref{myreference}.\\
\nameCref{myreference}, \namecref{myreference}.\\
\labelcref{myreference}, \labelcpageref{myreference}.\\
With \texttt{varioref}:\\
\Vref{myreference}, \vref{myreference}.
\end{document}
\end{fulldocumentlisting}



\clearpage

\begin{newTcbKey}[][doc new and updated={2014-09-19}{2023-07-03}]{blend into}{=\meta{name}}{style, no default, initially unset}
Used to comfortably blend into an existing schema of naming and numbering for
some selected cases. For example, a |tcolorbox| can be used to display
and entitle an image pretending to be a standard |figure| environment.
Here, \refKey{/tcb/title} is used instead of the standard |\caption|
and \refKey{/tcb/list text} can be used instead of the optional parameter
of the standard |\caption|.
Also, \refKey{/tcb/new/list type} is automatically adapted (changed with version 6.0.5).

Feasible values for \meta{name} are:
\begin{itemize}
\item\docValue{figures}: blend into the standard |figure| environment.
\item\docValue{tables}: blend into the standard |table| environment.
\item\docValue{listings}: blend into the standard |lstlisting| environment
  of the package \refPkg{listings} \cite{hoffmann:listings}.
  \begin{marker}
  Note that |blend into=listings| can only be used in the document content
  or, preferably, inside a |\AtBeginDocument| clause! Using it without
  |\AtBeginDocument| inside the preamble does not work since the |listings|
  packages initializes its counter also inside |\AtBeginDocument|.
  \end{marker}
\end{itemize}
\end{newTcbKey}

\enlargethispage*{5cm}
\begin{dispListing}
\begin{figure}[htb]
  \centering\includegraphics[height=4cm]{lichtspiel.jpg}
  \caption{A standard figure}
\end{figure}

\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure}
  \includegraphics[height=4cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}



\clearpage
\begin{docTcbKey}[][doc new=2015-03-13]{blend before title}{=\meta{value}}{no default, initially \docValue{colon}}
  This option formats the title output of \refKey{/tcb/new/blend into}.
  Note that this is a common |tcolorbox| option which should be set
  globally or in the normal option part of \refCom{newtcolorbox}.

Feasible values for \meta{value} are:
\begin{itemize}
\item\docValue{colon}: use name/number plus colon.
\item\docValue{dash}: use name/number plus dash.
\item\docValue{colon hang}: use name/number plus colon with hanging indent.
\item\docValue{dash hang}: use name/number plus dash with hanging indent.
\end{itemize}

\begin{dispListing}
\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  blend before title=dash hang,title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure with quite a long title}
  \includegraphics[height=5cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}
\end{docTcbKey}

\clearpage
\begin{docTcbKey}[][doc new=2015-03-13]{blend before title code}{=\meta{code}}{no default}
  This option formats the title output of \refKey{/tcb/new/blend into}.
  The \meta{code} takes one parameter, the name/number.
  Use this, if \refKey{/tcb/blend before title} is not flexible enough.

\begin{dispListing}
\newtcolorbox[blend into=figures]{myfigure}[2][]{float=htb,capture=hbox,
  blend before title code={\fbox{##1}\ },title={#2},every float=\centering,#1}

\begin{myfigure}{A tcolorbox figure}
  \includegraphics[height=6cm]{lichtspiel.jpg}
\end{myfigure}
\end{dispListing}
{\tcbusetemp}
\end{docTcbKey}



\clearpage
\subsection{Lists of \texttt{tcolorbox}es}\label{sec:listsof}
For figures and tables, \LaTeX\ provides the |\listoffigures| and
|\listoftables| commands to create lists of these numbered entities.
Also, a |tcolorbox| can be part of such a kind of list.
\begin{enumerate}
\item Assign a list \meta{name} by the \emph{initialization} option
  \refKey{/tcb/new/list inside}.
\item Optionally, a new \meta{type} for list entries may be assigned
  by the \emph{initialization} option \refKey{/tcb/new/list type}.
\item List entries a generated automatically within each new |tcolorbox|
  using the above initialization.
  \begin{itemize}
  \item If \refKey{/tcb/list entry} is set, the entry is generated with it.
  \item Otherwise, if \refKey{/tcb/title} is set, the entry is generated with it.
  \item Otherwise, the entry is generated with the current number and the environment name.
  \end{itemize}
\item The generated list is displayed by \refCom{tcblistof}.
\end{enumerate}

\begin{newTcbKey}{list inside}{=\meta{name}}{no default, initially unset}
Assigns a list or contents file to the generated |tcolorbox|es.
Entries to this list are saved to a file which gets the \meta{name} as
file name extension. The list is referenced by this name in
\refCom{tcblistof}.
For example:
\begin{dispListing}
list inside=exam
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.
\end{newTcbKey}


\begin{newTcbKey}{list type}{=\meta{type}}{no default, initially |tcolorbox|}
Optionally, some \meta{type} can be assigned to the list entries.
For a new \meta{type}, a macro |\l@|\meta{type} has to exist which controls
the format of the list entry. The default type is defined by
\begin{dispListing}
\newcommand*\l@tcolorbox{\@dottedtocline{1}{1.5em}{2.3em}}
\end{dispListing}
This is identical to the |\l@section| setting of \LaTeX. |\l@tcolorbox| can
be redefined or a new \meta{type} can be assigned.
\end{newTcbKey}


\clearpage
\begin{docCommand}[doc updated=2021-05-20]{tcblistof}{\oarg{macro}\marg{name}\oarg{short}\marg{title text}}
Displays the generated list of |tcolorbox|es with the given \meta{name}.
The heading is generated by \meta{macro}\oarg{short}\marg{title text} where \texttt{\textbackslash section}
is the default setting for \meta{macro}.
Here, as usual, \meta{title text} is the title of the section or chapter
while \meta{short} is a shorter title for headings and table of contents.
\begin{itemize}
\item If \meta{macro} ends with a |*|, \refCom{tcblistof} mimics the behavior of
  |\listoffigures| from the standard \LaTeX\ classes and adds the title
  to the left and right mark for headings.
\item If \meta{macro} starts with |\chapter|, a possible two column document setting
  is restored to one column (as standard \LaTeX\ classes do for |\listoffigures|).
\end{itemize}

\medskip
To display the list inside a subsection, use for example:
\begin{dispListing}
\tcblistof[\subsection]{exam}{List of Exercises}
\end{dispListing}
The result of the example is found as Subsection \ref{listofexercises} on
page \pageref{listofexercises}.

\medskip
To apply the list similar to |\listoffigures| for a report or book, use for example:
\begin{dispListing}
\tcblistof[\chapter*]{exam}{List of Exercises}
\end{dispListing}

\medskip
To set a short title for headings with the default |\section| setting, use for example:
\begin{dispListing}
\tcblistof{exam}[List of Exercises]{Elaborate List of Fine Exercises
                                    for all Students of my Course}
\end{dispListing}

\begin{marker}
The core of the list is generated by |\@starttoc|\marg{name} which
can be wrapped into an own macro.
\end{marker}
\end{docCommand}

\clearpage

\begin{marker}
The following options are not initialization options, but common options,
which are typically reasonable in connection with lists of |tcolorbox|es.
\end{marker}

\begin{docTcbKey}{list entry}{=\meta{text}}{no default, initially unset}
If the \flqq list of tcolorbox(es)\frqq\ feature described in
%Subsection \ref{sec:listsof} from page \pageref{sec:listsof}
the current subsection
is used, this key
describes the \meta{text} for an entry into the generated list, e.\,g.
\begin{dispListing}
list entry={\protect\numberline{\thetcbcounter}My beautiful Example}
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.\par
If |\thetcbcounter| is omitted, \refKey{/tcb/list entry} could be used for
unnumbered boxes too.
\begin{marker}
This is a customization option. For numbered boxes, \refKey{/tcb/list entry}
typically has not to be given, because this entry will be generated automatically.
\end{marker}
\end{docTcbKey}

\begin{docTcbKey}[][doc new=2014-09-19]{list text}{=\meta{text}}{style, no default}
This is a shortcut for setting \refKey{/tcb/list entry} to\\
|\protect\numberline{\thetcbcounter}|\meta{text}.
So, the following settings are identical:
\begin{dispListing}
list text={My beautiful Example},
list entry={\protect\numberline{\thetcbcounter}My beautiful Example}
\end{dispListing}
See Section \ref{listing:exercises} from page \pageref{listing:exercises}
for a complete example.
\end{docTcbKey}

\begin{docTcbKey}{add to list}{=\marg{list}\marg{type}}{no default, initially unset}
If the \flqq list of tcolorbox(es)\frqq\ feature described in
%Subsection \ref{sec:listsof} from page \pageref{sec:listsof}
the current subsection
is used, list entries are
generated automatically. With this key, you can enforce an entry to the
given \meta{list} with the given \meta{type}.
This issues:\par
|\addcontentsline|\marg{list}\marg{type}\marg{entry text}\par
\meta{entry text} may be given by \refKey{/tcb/list entry}.
\begin{marker}
This is a customization option. For numbered boxes, this feature is configured
automatically, where
\meta{list} is set by \refKey{/tcb/new/list inside} and
\meta{type} is set by \refKey{/tcb/new/list type}
\end{marker}
\end{docTcbKey}