tcolorbox

What this skill does

# tcolorbox — Colored & Framed Boxes

**CTAN:** https://ctan.org/pkg/tcolorbox  
**Manual:** `texdoc tcolorbox` (~500 pages)

## Setup

```latex
\usepackage[most]{tcolorbox}
% 'most' loads: skins, breakable, listings, theorems, fitting, hooks, xparse
% For minimal: \usepackage{tcolorbox} then \tcbuselibrary{...}

\tcbuselibrary{skins}       % enhanced appearance
\tcbuselibrary{breakable}   % boxes across pages
\tcbuselibrary{theorems}    % theorem integration
\tcbuselibrary{listings}    % code listings in boxes
\tcbuselibrary{listingsutf8} % UTF-8 code listings
```

## Basic Usage

```latex
\begin{tcolorbox}
  This is a simple colored box.
\end{tcolorbox}

\begin{tcolorbox}[colback=blue!5, colframe=blue!75!black, title=My Title]
  A box with title and custom colors.
\end{tcolorbox}
```

## Common Options

| Option | Default | Description |
|--------|---------|-------------|
| `colback` | `black!5!white` | Background color |
| `colframe` | `black!75!white` | Frame color |
| `coltitle` | `white` | Title text color |
| `colbacktitle` | (from `colframe`) | Title background |
| `coltext` | `black` | Body text color |
| `title` | (none) | Box title |
| `fonttitle` | | Title font (`\bfseries\large`) |
| `fontupper` | | Upper (main) body font |
| `fontlower` | | Lower part font |
| `arc` | `1mm` | Corner radius |
| `boxrule` | `0.5mm` | Frame thickness |
| `leftrule` | (from boxrule) | Left rule only |
| `toprule` | (from boxrule) | Top rule only |
| `width` | `\linewidth` | Box width |
| `left` | `4mm` | Left padding |
| `right` | `4mm` | Right padding |
| `top` | `2mm` | Top padding |
| `bottom` | `2mm` | Bottom padding |
| `boxsep` | `1mm` | All-sides padding |
| `sharp corners` | | Remove rounding |
| `rounded corners` | ✅ | Default |
| `halign` | `justify` | `left`, `center`, `right`, `justify` |
| `valign` | `top` | `top`, `center`, `bottom` |

## Box Styles

### Titled Box

```latex
\begin{tcolorbox}[
  colback=yellow!10,
  colframe=yellow!50!black,
  title=Warning,
  fonttitle=\bfseries,
  coltitle=black,
]
  Be careful with this operation.
\end{tcolorbox}
```

### Left Bar (callout style)

```latex
\begin{tcolorbox}[
  enhanced,
  colback=blue!5,
  colframe=blue!5,       % hide frame
  borderline west={3pt}{0pt}{blue!70},
  sharp corners,
  boxrule=0pt,
]
  \textbf{Note:} This is a callout-style box.
\end{tcolorbox}
```

### Minimalist

```latex
\begin{tcolorbox}[
  enhanced,
  colback=gray!5,
  colframe=gray!5,
  boxrule=0pt,
  arc=0pt,
  left=10pt,
]
  Clean, simple box.
\end{tcolorbox}
```

### Upper/Lower Parts

```latex
\begin{tcolorbox}[
  colback=white,
  colframe=blue!50!black,
  title=Theorem,
]
  $a^2 + b^2 = c^2$
  \tcblower
  This is the proof part (lower section).
\end{tcolorbox>
```

## Breakable Boxes (Multi-Page)

```latex
\tcbuselibrary{breakable}

\begin{tcolorbox}[breakable, colback=white, colframe=blue!50!black]
  Very long content that may span multiple pages...
  % The box will automatically break at page boundaries
\end{tcolorbox}

% Enhanced breakable (better visuals)
\begin{tcolorbox}[enhanced jigsaw, breakable, colback=white, colframe=blue!50!black]
  Long content...
\end{tcolorbox}
```

## Theorem Boxes

```latex
\tcbuselibrary{theorems}

% Define theorem types
\newtcbtheorem[number within=section]{theorem}{Theorem}{
  colback=blue!5,
  colframe=blue!50!black,
  fonttitle=\bfseries,
}{thm}

\newtcbtheorem[number within=section]{definition}{Definition}{
  colback=green!5,
  colframe=green!50!black,
  fonttitle=\bfseries,
}{def}

\newtcbtheorem[number within=section]{example}{Example}{
  colback=yellow!5,
  colframe=yellow!50!black,
  fonttitle=\bfseries,
}{ex}

\newtcbtheorem[number within=section]{proposition}{Proposition}{
  colback=red!5,
  colframe=red!50!black,
  fonttitle=\bfseries,
}{prop}

% Usage — two arguments: title and label
\begin{theorem}{Pythagoras}{pythagoras}
  For a right triangle with legs $a$, $b$ and hypotenuse $c$:
  \[ a^2 + b^2 = c^2 \]
\end{theorem}

\begin{definition}{Group}{group}
  A \emph{group} is a set $G$ with a binary operation...
\end{definition}

% Reference: Theorem~\ref{thm:pythagoras}
```

### Theorem with Proof Below

```latex
\newtcbtheorem{mythm}{Theorem}{
  colback=blue!5,
  colframe=blue!50!black,
  fonttitle=\bfseries,
  separator sign={\ ---},
  description delimiters parenthesis,
}{thm}

\begin{mythm}{Fundamental Theorem}{fundamental}
  Every continuous function on $[a,b]$ is integrable.
  \tcblower
  \textit{Proof.} By construction... $\square$
\end{mythm}
```

## Code Boxes (Listings)

```latex
\tcbuselibrary{listings}
% or \tcbuselibrary{listingsutf8} for UTF-8

% Inline listing box
\begin{tcblisting}{
  colback=gray!5,
  colframe=gray!75!black,
  listing only,        % show only code (not rendered)
  title=Python Example,
  listing options={language=Python, basicstyle=\ttfamily\small},
}
def hello():
    print("Hello, world!")
\end{tcblisting}

% Side-by-side: code + output
\begin{tcblisting}{
  colback=white,
  colframe=blue!50!black,
  listing side text,   % code left, text right
  title=LaTeX Example,
}
$\int_0^1 x^2\, dx = \frac{1}{3}$
\end{tcblisting}
```

### Code Box Style

```latex
\newtcblisting{codebox}[2][]{
  colback=gray!5,
  colframe=gray!80!black,
  title=#2,
  fonttitle=\bfseries\ttfamily,
  listing only,
  listing options={
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    commentstyle=\color{green!60!black},
    stringstyle=\color{red!70!black},
    #1
  },
}

% Usage
\begin{codebox}[language=Python]{my\_script.py}
import numpy as np
x = np.linspace(0, 1, 100)
\end{codebox}
```

### Using minted Instead of listings

```latex
\tcbuselibrary{minted}

\begin{tcblisting}{
  listing engine=minted,
  minted language=python,
  minted style=monokai,
  colback=gray!10,
  listing only,
}
def hello():
    print("Hello!")
\end{tcblisting}
```

## Skins

```latex
\tcbuselibrary{skins}

% Enhanced (required for many visual features)
\begin{tcolorbox}[enhanced, ...]

% Bicolor (different upper/lower colors)
\begin{tcolorbox}[bicolor, colback=blue!10, colbacklower=green!10, ...]

% Beamer style
\begin{tcolorbox}[beamer, colback=blue!10, colframe=blue!50!black]

% Watermark
\begin{tcolorbox}[enhanced, watermark text=DRAFT, watermark color=red!20]
```

## Custom Box Definitions

```latex
% Simple named box
\newtcolorbox{important}{
  colback=red!5,
  colframe=red!50!black,
  fonttitle=\bfseries,
  title=Important,
}

% Box with parameter
\newtcolorbox{mybox}[1]{
  colback=blue!5,
  colframe=blue!50!black,
  title=#1,
  fonttitle=\bfseries,
}

% Box with optional + required args
\newtcolorbox{notebox}[2][]{
  enhanced,
  colback=yellow!10,
  colframe=yellow!50!black,
  title=#2,
  #1,  % optional overrides
}

% Usage
\begin{important}
  Don't forget this!
\end{important}

\begin{mybox}{Title Here}
  Content.
\end{mybox}

\begin{notebox}[colback=red!10]{Warning}
  Override the background.
\end{notebox}
```

## Complete Example: Lecture Notes Setup

```latex
\usepackage[most]{tcolorbox}

\newtcbtheorem[number within=section]{theorem}{Theorem}{
  enhanced, breakable,
  colback=blue!3, colframe=blue!50!black,
  fonttitle=\bfseries,
  separator sign={.},
}{thm}

\newtcbtheorem[number within=section]{definition}{Definition}{
  enhanced, breakable,
  colback=green!3, colframe=green!50!black,
  fonttitle=\bfseries,
}{def}

\newtcbtheorem[number within=section]{example}{Example}{
  enhanced, breakable,
  colback=yellow!5, colframe=yellow!50!black,
  fonttitle=\bfseries,
}{ex}

\newtcolorbox{remark}{
  enhanced,
  colback=gray!5, colframe=gray!5,
  borderline west={3pt}{0pt}{gray!50},
  sharp corners, boxrule=0pt,
}

\newtcolorbox{warning}{
  enhanced,
  colback=red!5, colframe=red!50!black,
  fonttitle=\bfseries, title=Warning,
}
```

## Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Box doesn't break across pages | Missing `breakable` | Add `breakable` option |
| Visual artifacts when breaking | Standard skin + breakable | Use `enhanced ji