standalone

standalone is a class for typesetting a single building block — a figure, a TikZ picture, a table — as a document complete in itself. The output is cropped tightly to the content: a PDF of just the figure, with no surrounding page, page number, or margin. Paired with the package of the same name, that figure file can be pulled into your main document with \input unchanged. Written by Martin Scharrer, it lets one figure serve both on its own and as part of a larger document.

What standalone is for

When you write a large document, you often want to split figures and TikZ pictures into their own files and pull them into the body. But to compile such a figure file on its own and check it, you have to keep adding scaffolding — \documentclass, \begin{document} — and the output is just the figure sitting in the corner of a big white body-text page. The standalone class solves both problems. Put \documentclass{standalone} at the top of a figure file and you can compile that one piece on its own, with the output cropped tightly to the size of the content — a PDF (or DVI/PS) with no page number, header, or footer.

standalone has two faces. One is the class you use in the figure file (\documentclass{standalone}); the other is the package you load in the main document (\usepackage{standalone}). The class plays the role of “set one piece on its own,” the package the role of “include that piece in the main document” — the two form a pair. Let us start with the class.

Both the standalone class and package require the xkeyval package. The package additionally needs currfile (which itself uses filehook) to track the names of included files, and gincltex and filemod for the build-to-image feature. All of these ship with TeX Live and MiKTeX.

Using it as a class

You use it just like an ordinary LaTeX document. Select the class with \documentclass{standalone}, load whatever packages the figure needs in the preamble (for TikZ, tikz, and so on), and write the content directly between \begin{document} and \end{document}. The class enables the **crop option** (see below) by default, which crops the output to the size of the content.

\documentclass{standalone}
\usepackage{tikz}
\begin{document}
\begin{tikzpicture}
  \draw (0,0) rectangle (2,1) node[midway] {Example};
\end{tikzpicture}
\end{document}

Compiled on its own, this yields a single PDF cropped to the rectangle alone. Two things to watch when writing: do not leave blank lines before or after the content, and put \begin{document} and \end{document} each on their own line. The standalone class treats the whole content as one block, so a trailing blank line is read as a paragraph \linewidth wide, which can add stray space to the right of the figure.

For a TikZ picture, the convenient route is the **tikz option**, as in \documentclass[tikz]{standalone}. It loads the tikz package and even configures the tikzpicture environment to be cropped onto its own page (internally it sets multi=tikzpicture and varwidth=false). For PSTricks pictures there is a matching pstricks option.

Key class options

Options go in the brackets, comma-separated. Most standalone options are boolean: omit the value and you get true; unless stated otherwise the initial value is false. These options are not passed down to the underlying class (article by default) — standalone consumes them itself to avoid name clashes. The most important ones follow.

The one you reach for most is **border**. With \documentclass[border=5pt]{standalone} the cropped figure gets a 5pt margin on all four sides. To pass several values separated by spaces, wrap the whole value in braces: border={10pt 5pt}. Because border and varwidth have no global effect, you can change them later — in the preamble, or even mid-document when multi is enabled — with **\standaloneconfig{...}**.

One historical note. Before v1.0 the preview option was the default, and the default border was about 0.5bp. Since v1.0 crop is the default and the border is 0pt. To restore the old behaviour, put \standaloneconfig{preview,border=0.50001bp} in the configuration file, or state these as options explicitly.

Including it as a package

The package is standalone’s other face. Load \usepackage{standalone} as early as possible in the main document’s preamble, and the package redefines \documentclass so that everything from a figure file’s \documentclass up to its \begin{document} is skipped when you \input it. The figure file’s document environment is treated as a plain TeX group, while the main document’s real document environment is unaffected (anything after \end{document} is ignored too). In effect the figure file’s preamble is stripped on inclusion, and a bare \input{figure} flows just the content into the body.

The prerequisite is that the main document must itself load every package the figure files need. Since the figure file’s preamble is skipped on inclusion, packages like tikz have to be loaded by the main document. Here is the official example of a main document loading the standalone package and including a figure with \input inside a figure environment.

\documentclass{article}
% load the standalone package early
\usepackage{standalone}
% load everything the sub-files need
\usepackage{tikz}

\begin{document}
% ...
\begin{figure}
  \input{figure}% the standalone file from above
  \caption{A sub-file}
\end{figure}
% ...
\end{document}

The point is that the same figure.tex works without changing a single character, whether on its own or through the main document. Compiled alone it becomes a cropped one-page PDF; \input from the main document drops just the figure into the body. It is recommended to manage floats in the main document — keep the figure environment there and put only the content in the standalone file (in the standalone class float defaults to false so that crop/preview work).

When you want the main document to collect figure-file preambles automatically, load it as \usepackage[subpreambles=true]{standalone}. Each figure file’s preamble is then gathered into an auxiliary file and pulled into the main document on the next run. Add the sort option and the packages (with their options) loaded by each figure are accumulated without duplicates and loaded via \PassOptionsToPackage, avoiding option clashes. If you would rather copy them into the main preamble by hand, the print option writes out the list.

Building to images, and look-alikes

standalone can also bake a figure into an image instead of including its source. In the main document, write \includestandalone{figure} in place of \input{figure} and it compiles the figure file separately when needed to produce an image (a PDF, say), then pulls that in with \includegraphics. The benefit is that complex figures need not be recompiled every time, so the main build is faster. Because this calls an external command, it requires the -shell-escape option at compile time.

Beyond that, options like convert, png, jpg, and svg enable a conversion feature that exports a standalone file to an image (an external conversion tool is required). This is handy when you want to distribute a figure as a PNG or SVG on its own.

Two look-alikes serve similar ends: **subfiles and TikZ’s external library**. subfiles works in the opposite direction — a sub-file imports the *main* document’s preamble, whereas standalone lets a sub-file’s preamble be imported *into* the main document. So standalone suits reusing one figure across several documents (a paper, a presentation, a thesis), while subfiles suits a one-to-one relationship between main and sub-file. TikZ’s external writes temporary images out from the main file, working the opposite way to standalone.