tcolorbox — Colored & Framed Boxes

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

Setup

\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

\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

\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)

\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

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

Upper/Lower Parts

\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)

\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

\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

\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)

\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

\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

\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

\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

% 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

\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 jigsaw + breakable
enhanced features not working	Forgot skins library	Use \tcbuselibrary{skins} or [most]
Theorem numbering wrong	Wrong counter	Check number within option
Listing encoding errors	UTF-8 in code	Use listingsutf8 library
Overfull boxes	Box wider than margins	Set width=\linewidth explicitly
Colors too bright	Full saturation	Use color!intensity like blue!50!black
\newtcbtheorem needs 2 args	Forgot label	\begin{thm}{Title}{label} — both required
tcolorbox + hyperref conflict	Load order	Load tcolorbox after hyperref

Tips

• Use [most] when loading to get all common libraries
• enhanced skin is needed for borderline, watermark, shadow, etc.
• Combine breakable + enhanced jigsaw for clean page breaks
• Mix \newtcbtheorem with \newtcolorbox — theorems for numbered, plain boxes for unnumbered
• Use \tcbset{...} for global defaults across all boxes
• Colors: mix with black for professional look: blue!50!black not blue