mathtools

Once amsmath is loaded and you start setting mathematics, a few just-out-of-reach things come into view — the colon in := sits a touch too low, you want labels above *and* below a long arrow that spans a line, you want the bars of an absolute value to stretch to fit their contents. mathtools is the package that takes care of all of these. It is an extension that loads amsmath and then improves it, so the single line \usepackage{mathtools} pulls amsmath in as well. This page walks through its most-used additions: a proper :=, the extensible arrow \xrightarrow, the square-cornered \overbracket, the self-sizing \DeclarePairedDelimiter, the zero-width \mathclap, the pre-script \prescript, and column-aligned matrices via matrix*.

What mathtools is

mathtools is, in the words of its official manual, “an extension package to amsmath.” Taking amsmath’s status as the de facto standard for math typesetting as given, it fixes several of amsmath’s remaining deficiencies and bugs, and adds tools that prove handy in everyday typesetting. The key point is that mathtools requires amsmath under the hood and loads it automatically. So you need not name amsmath separately — this single line in the preamble suffices.

\usepackage{mathtools}

When you want to pass options to amsmath, mathtools relays them. As the manual shows, \usepackage[fleqn,tbtags]{mathtools} means the same as writing \usepackage[fleqn,tbtags]{amsmath} followed by \usepackage{mathtools}. In other words, options you give when loading mathtools reach the amsmath underneath.

mathtools’ feature set is broad, and we cannot cover all of it here. This page narrows to the high-frequency additions of the kind a reference such as Okumura’s *Introduction to LaTeX2e* would also touch on. There are further facilities — extended case distinctions (dcases), control over equation numbering (showonlyrefs), arrows within alignments (\ArrowBetweenLines) — but the alignment details belong to the separate page “Displayed, aligned & numbered equations.”

A proper assignment sign — the `\coloneqq` family

Typing the definitional “:=” literally as := in math mode comes out clumsier than you would expect. The : is treated as punctuation, not a relation, so the spacing around it is off, and the colon drops a little below the center line of the =. mathtools’ \coloneqq sets a “:=” with the colon centered at the correct height against the equals and with proper relation spacing. For the reverse, “=:”, use \eqqcolon.

\[
  f(x) \coloneqq x^2 + 1, \qquad y \eqqcolon g(x)
\]

Here the left formula sets the := for “define f(x) as x²+1,” and the right sets the =: for “write g(x) as y,” each with the colon neatly centered. There is also a double colon \dblcolon (::), and colon-with-approximation or -similarity forms such as \colonapprox and \colonsim.

One caveat. In a 2022 update, mathtools regularized the canonical names of these colon symbols (to align them with other packages). The familiar names \coloneqq and \eqqcolon remain available for compatibility, but in the new scheme \coloneq and friends are the canonical forms. The old names are kept so that existing documents keep compiling.

Extensible arrows — `\xrightarrow` and `\xleftarrow`

The ordinary \rightarrow (→) and \Rightarrow (⇒) are fixed in length, and look awkward when a label on top is wider than the arrow. amsmath provides exactly two arrows that stretch horizontally to fit a label: \xrightarrow and \xleftarrow. The syntax is \xrightarrow[below label]{above label}, with the **braces { } placed above the arrow and the brackets [ ] below** it (the brackets are optional). The arrow grows to the width of the labels.

\[
  A \xrightarrow{f} B \xrightarrow[\sim]{g} C,
  \qquad
  X \xleftarrow[n \to \infty]{\varphi_n} Y
\]

Here the arrow from A to B is a right-stretching arrow carrying f above, and from B to C an arrow with g above and ∼ below, each stretched to the width of its labels. On the right is a left-pointing arrow with the map φ_n above and the limiting condition n→∞ below.

amsmath supplies only these two stretchable arrows, but mathtools enlarges the family greatly, following the same naming scheme: the double-line \xRightarrow, \xLeftarrow, and \xLeftrightarrow; the two-headed \xleftrightarrow; the hooked \xhookrightarrow and \xhookleftarrow; the map \xmapsto; plus harpoons (half-barbed arrows) and longer variants such as \xlongrightarrow. All take the same [below]{above} form.

Square braces — `\overbracket` and `\underbracket`

Standard LaTeX (and amsmath) give \overbrace and \underbrace, which draw a curly brace above or below an expression. To these mathtools adds \overbracket and \underbracket, which draw a square (right-angle) bracket instead — not the rounded curly shape but a bracket whose ends turn at right angles, like “⌜ ⌟”, which can read more clearly when marking the extent of a diagram or structure.

\overbracket takes two optional arguments: the first is the rule thickness, the second the bracket height, written in the order \overbracket[rule thickness][height]{contents}. By default the rule thickness equals that of \overbrace (about 5/18 ex) and the height is about 0.7 ex, values chosen to look good at any font size. Give the brackets only when you want to change the thickness or height. The label on top is attached with ^{ } (or _{ } below), just as with the curly form.

\[
  \underbracket{a + b + c}_{\text{3 terms}}
  \quad\text{vs}\quad
  \underbrace{a + b + c}_{\text{3 terms}}
\]

Here the same “a+b+c” gets, on the left, a right-angle bracket from \underbracket and, on the right, a curly brace from \underbrace, each with the note “3 terms” beneath. Side by side, the difference between the square bracket and the rounded brace is plain.

Self-sizing fences — `\DeclarePairedDelimiter`

When setting an absolute value |x| or a norm ‖x‖, a fixed-size bar overshoots its contents and looks clumsy if the body is something tall like a fraction. amsmath’s manual suggests a homemade \newcommand*\abs[1]{\lvert#1\rvert}, but while that gets the horizontal spacing right, the bars do not grow for a tall body such as \abs{\frac{a}{b}}, and the result breaks down. mathtools’ \DeclarePairedDelimiter defines such a matched pair of fences in one stroke, complete with auto-sizing. Write this in the preamble.

\DeclarePairedDelimiter\abs{\lvert}{\rvert}
\DeclarePairedDelimiter\norm{\lVert}{\rVert}

With this in place, \abs and \norm each gain three modes of use. First, **plain \abs{x} sets fixed-size bars (enough when the body is short). Second, the starred \abs*{x}** wraps the body in \left … \right and stretches automatically to its height. Third, the **optional-argument form \abs[\big]{x}** sizes the fences by hand, choosing from the four steps \big, \Big, \bigg, and \Bigg.

\[
  \abs{x} = \abs{-x}, \qquad
  \abs*{\frac{a}{b}} = \frac{\abs{a}}{\abs{b}}, \qquad
  \norm[\big]{v}
\]

Here \abs{x} and \abs{-x} are normal-size bars, \abs*{\frac{a}{b}} is a pair of bars stretched to the height of the fraction, and \norm[\big]{v} is a double bar enlarged by one \big step. For the underlying mechanics of fences, see also the page “Delimiters (\left \right).”

Zero-width centering, and pre-scripts

Three more frequently used tools, taken together. The first is \mathclap. When the condition placed under a sum or product is wider than the operator itself, that width opens up extra space across the whole formula. \mathclap{…} puts its argument in a zero-width box and centers it symmetrically, so the condition stays visible while the formula’s width is held to that of the operator. There are also left- and right-aligned \mathllap and \mathrlap, and a text-mode \clap.

\[
  \sum_{\mathclap{1 \le i \le j \le n}} a_{ij}
\]

Here the wide condition “1 ≤ i ≤ j ≤ n” sits under the summation sign, but wrapping it in \mathclap centers it under the sign and leaves no wasted space to the left or right of the formula. Remove \mathclap and the area around the summation sign stretches out by the width of the long condition.

The second is \prescript, which places a superscript and subscript before (to the left of) a symbol. It takes three arguments, in the order \prescript{pre-superscript}{pre-subscript}{base}. It is handy for chemical isotope notation and for mathematical notations that use left indices. Uranium-238, for example, is written with the mass number 238 as the pre-superscript and the atomic number 92 as the pre-subscript.

\[
  \prescript{238}{92}{\mathbf{U}}, \qquad
  \prescript{n}{}{C}_{k}
\]

Here the left is the uranium isotope notation, with 238 at the upper left and 92 at the lower left of the element symbol U; the right places n at the upper left of C while still attaching k at the lower right as usual. When you do not need a pre-subscript, leave the second argument empty as {}.

The third is \shortintertext. amsmath’s \intertext lets you slot text between rows while preserving the alignment, but its space above and below can be a little too generous. \shortintertext{…} is a tightened version, sitting better when you want a brief remark between lines. Both \intertext and \shortintertext also work inside the gather environment.

Column-aligned matrices — the `matrix*` family

amsmath’s matrix environments (matrix, pmatrix, bmatrix, and so on) set every column centered, always. When entries with and without a minus sign are mixed, centering misaligns the digits and reads poorly. mathtools provides starred environments corresponding to each — matrix*, pmatrix*, bmatrix*, Bmatrix*, vmatrix*, Vmatrix* — that accept an optional argument choosing the column alignment. Write \begin{pmatrix*}[r], giving the same column specifier as the array environment (r, l, c); the default is c.

\[
  \begin{pmatrix*}[r]
    -1 & 3 \\
     2 & -4
  \end{pmatrix*}
\]

Here each column of the parenthesized matrix is set right-aligned, so the right edges of -1 and 2, and of 3 and -4, line up and the minus signs jut cleanly to the left. With the plain pmatrix the entries would be centered, making the digits look offset by the width of the minus sign. For the basics of matrices themselves, see the page “Matrices & arrays.”

Setting options — `\mathtoolsset`

Many of mathtools’ behaviors can be tuned by flipping switches (to true/false and the like). The command that does this in one place is \mathtoolsset{…}, normally written in the preamble to take effect document-wide. Keys are listed comma-separated, given either as key=value or, where the value is obvious, as a bare key.

\mathtoolsset{
  showonlyrefs = true,
  centercolon
}

Some commonly used keys. showonlyrefs=true numbers only those equations referenced from the text and hides numbers on the rest (though you must refer with \eqref, not \ref). centercolon turns on the behavior that **sets a : at the center height** as a relation. Beyond these are many finer keys, such as smallmatrix-align for the default alignment of the small matrix variants, and prescript-sub-format / prescript-sup-format to change the font of \prescript’s indices.