PGF/TikZ Manual

The TikZ and PGF Packages
Manual for version 3.1.10


45 Background Library

  • TikZ Library backgrounds

  • \usetikzlibrary{backgrounds} % and plain
    \usetikzlibrary[backgrounds] % Cont

    This library defines “backgrounds” for pictures. This does not refer to background pictures, but rather to frames drawn around and behind pictures. For example, this package allows you to just add the framed option to a picture to get a rectangular box around your picture or gridded to put a grid behind your picture.

The first use of this library is to make the following key available:

  • /tikz/on background layer=options(no default)

  • This key can (only) be used with a {scope} or \scoped. It will cause everything inside the scope to be typeset on a background layer.

    The options will be executed inside background scope. This is useful since other options passed to the {scope} environment will be executed before the actual background material starts and, thus, will have no effect on it.

    (-tikz- diagram)

    \usetikzlibrary {backgrounds}
    % On main layer:
    \fill[blue] (0,0) circle (1cm);

    \begin{scope}[on background layer={color=yellow}]
    \fill (-1,-1) rectangle (1,1);

    \begin{scope}[on background layer]
    \fill[black] (-.8,-.8) rectangle (.8,.8);

    % On main layer again:
    \fill[blue!50] (-.5,-1) rectangle (.5,1);

    A scope with this option set should not be “deeply nested” inside the picture since changes to the graphic state (like the color or the transformation matrix) “do not survive a layer switch”, see also Section 113 for details. In particular, setting, say, the line width at the beginning of a picture will not have an effect on the background picture.

    For this reason, it may be useful to setup the following style:

When this package is loaded, the following styles become available:

  • /tikz/show background rectangle(style, no value)

  • This style causes a rectangle to be drawn behind your graphic. This style option must be given to the {tikzpicture} environment or to the \tikz command.

    (-tikz- diagram)

    \usetikzlibrary {backgrounds}
    \begin{tikzpicture}[show background rectangle]
    \draw (0,0) ellipse (10mm and 5mm);

    The size of the background rectangle is determined as follows: We start with the bounding box of the picture. Then, a certain separator distance is added on the sides. This distance can be different for the \(x\)- and \(y\)-directions and can be set using the following options:

    • /tikz/inner frame xsep=dimension (no default, initially 1ex)

    • Sets the additional horizontal separator distance for the background rectangle.

    • /tikz/inner frame ysep=dimension (no default, initially 1ex)

    • Same for the vertical separator distance.

    • /tikz/inner frame sep=dimension(no default)

    • Sets the horizontal and vertical separator distances simultaneously.

    The following two styles make setting the inner separator a bit easier to remember:

    • /tikz/tight background(style, no value)

    • Sets the inner frame separator to 0pt. The background rectangle will have the size of the bounding box.

    • /tikz/loose background(style, no value)

    • Sets the inner frame separator to 2ex.

    You can influence how the background rectangle is rendered by setting the following style:

  • /tikz/framed(style, no value)

  • This is a shorthand for show background rectangle.

  • /tikz/gridded(style, no value)

  • This is a shorthand for show background grid.

  • /tikz/show background bottom(style, no value)

  • Works like the style for the top line.

  • /tikz/show background left(style, no value)

  • Works similarly.

  • /tikz/show background right(style, no value)

  • Works similarly.