Optional arguments in the `\newtcolorbox` macro

Question

According to the tcolorbox package's user manual, the \newtcolorbox macro's usage is as follows (p. 15).

The following is given as a usage example. (p. 15).

Here's what I don't understand about this example.

1. In the definition part: What do the empty square brackets mean? That there are no defaults, i.e. that the 2 options are mandatory? If so, why not simply omit these brackets, as in the following example that is given on the same page?

2. In the usage part: Why is the first argument ([colback=yellow]) written within square brackets, whereas the second argument ({Hello there}) written within curly braces? If there were more than 2 arguments, how would they be specified?

Answer 1

The definition is analogous to what is offered by \newcommand where you can define something via

\newcommand{\mycmd}[2][x]{optional: #1, mandatory: #2}

which defines a command \mycmd to take two arguments [2]. The first argument is optional and will take the value x if you don't use it. So, \mycmd{a} is valid, as is \mycmd[b]{a}.

Specific to your questions:

1. In the definition part: What do the empty square brackets mean? That there are no defaults, i.e. that the 2 options are mandatory? If so, why not simply omit these brackets, as in the following example that is given on the same page?

The empty square brackets refer to the fact that the newly-defined tcolorbox command will take a single optional argument, and the default value for that optional argument if it isn't specified by the user will be blank.

2. In the usage part: Why is the first argument ([colback=yellow]) written within square brackets, whereas the second argument ({Hello there}) written within curly braces? If there were more than 2 arguments, how would they be specified?

This is because the creation of mybox was defined with

\newtcolorbox{mybox}[2][]

in the first and

\newtcolorbox{mybox}[1]

in the second.

The first states that mybox will take two arguments [2] of which the first will be optional and default to "blank" if not supplied. The second states that mybox will only take a single argument [1] and that it is a mandatory argument.

If you want, say, 5 arguments, all mandatory, then you'd use

\newtcolorbox{mybox}[5]

If you want a single, optional argument, together with (say) 3 mandatory arguments, then use

\newtcolorbox{mybox}[4][default]

where default is the default definition of the optional argument if it's not specified. Moreover, the optional argument is always the first #1 parameter.

Answer 2

The [] is empty here in the first example, but allows for specification of optional arguments to the call of the mybox environment, i.e. \begin{mybox}[colback=yellow]{Foo} title would have a yellow background and the the title foo. The second example would not allow for optional arguments, that's all.

The definition of box environments with two or more mandatory arguments is as usual with \newcommand: \newtcolorbox{foo}[2]{options}.

If more optional arguments are necessary, use the \DeclareTColorBox feature of tcolorbox.

\documentclass{article}

\usepackage[most]{tcolorbox}

\newtcolorbox{mybox}[2][]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=-2mm},
title=#2,#1}


\newtcolorbox{myboxwithtwoparameters}[2]{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=-2mm},
title=#2,code={\addtocontents{toc}{#2}}}


\DeclareTColorBox{mytotalbox}{O{}mO{-2mm}}{colback=red!5!white,
colframe=red!75!black,fonttitle=\bfseries,
colbacktitle=red!85!black,enhanced,
attach boxed title to top center={yshift=#3},
title=#2,#1}


\begin{document}
\tableofcontents
\begin{mybox}[colback=yellow]{Hello there}
This is my own box with a mandatory title
and options.
\end{mybox}

\begin{myboxwithtwoparameters}{Hello there}{Hello Darkness my old friend}
Foo
\end{myboxwithtwoparameters}

\begin{mytotalbox}[colback=yellow]{Hello there}[-5mm]
This is my own box with a mandatory title
and options.
\end{mytotalbox}


\end{document}