TikZ and PGF Manual

Since this path operation is one of the most involved around, let us go over it step by step.

Order of the parts of the specification. Everything between “node” and the opening brace of a node is optional. If there are ⟨foreach statements⟩, they must come first, directly following “node”. Other than that, the ordering of all the other elements of a node specification (the ⟨options⟩, the ⟨name⟩, ⟨coordinate⟩, and ⟨animation attribute⟩) is arbitrary, indeed, there can be multiple occurrences of any of these elements (although for the name and the coordinate this makes no sense).

The text of a node. At the end of a node, you must (normally) provide some ⟨node contents⟩ in curly braces; indeed, the “end” of the node specification is detected by the opening curly brace. For normal nodes it is possible to use “fragile” stuff inside the ⟨node contents⟩ like the \verb command (for the technically savvy: code inside the ⟨node contents⟩ is allowed to change catcodes; however, this rule does not apply to “nodes on a path” to be discussed later).

Instead of giving ⟨node contents⟩ at the end of the node in curly braces, you can also use the following key:

Specifying the location of the node. Nodes are placed at the last position mentioned on the path. The effect of adding “at” to a node specification is that the coordinate given after at is used instead. The at syntax is not available when a node is given inside a path operation (it would not make any sense there).

Another aspect of the “location” of a node is whether it appears in front of or behind the current path. You can change which of these two possibilities happens on a node-by-node basis using the following keys:

The options of a node. The ⟨options⟩ is an optional list of options that apply only to the node and have no effect outside. The other way round, most “outside” options also apply to the node, but not all. For example, the “outside” rotation does not apply to nodes (unless some special options are used, sigh). Also, the outside path action, like draw or fill, never applies to the node and must be given in the node (unless some special other options are used, deep sigh).

The shape of a node. As mentioned before, we can add a border and even a background to a node:

The “border” is actually just a special case of a much more general mechanism. Each node has a certain shape which, by default, is a rectangle. However, we can also ask TikZ to use a circle shape instead or an ellipse shape (you have to include one of the shapes.geometric library for the latter shape):

There are many more shapes available such as, say, a shape for a resistor or a large arrow, see the shapes library in Section 71 for details.

To select the shape of a node, the following option is used:

Animating a node. When you say :⟨animation attribute⟩={⟨options⟩}, an animation of the specified attribute is added to the node. Animations are discussed in detail in Section 26. Here is a typical example of how this syntax can be used:

The foreach statement for nodes. At the beginning of a node specification (and only there) you can provide multiple ⟨foreach statements⟩, each of which has the form foreach ⟨var⟩ in ⟨list⟩ (note that there is no backslash before foreach). When they are given, instead of a single node, multiple nodes will be created: The ⟨var⟩ will iterate over all values of ⟨list⟩ and for each of them, a new node is created. These nodes are all created using all the text following the ⟨foreach statements⟩, but in each copy the ⟨var⟩ will have the current value of the current element in the ⟨list⟩.

As an example, the following two codes have the same effect:

When you provide several foreach statements, they work like “nested loops”:

As the example shows, a ⟨list⟩ can contain ellipses (three dots) to indicate that a larger number of numbers is meant. Indeed, you can use the full power of the \foreach command here, including multiple parameters and options, see Section 88.

Styles for nodes. The following styles influence how nodes are rendered:

Name scopes. It turns out that the name of a node can further be influenced using two keys:

Inside {tikzpicture} this is an abbreviation for \path coordinate.

This command can only be used inside the ⟨text⟩ argument of a node path operation. It works a little bit like a \part command in LaTeX. It will stop the typesetting of whatever node part was typeset until now and then start putting all following text into the node part named ⟨part name⟩ – until another \nodepart is encountered or until the node ⟨text⟩ ends. The ⟨options⟩ will be local to this part.

You will have to lookup which parts are defined by a shape.

The following styles influences node parts:

Since the ⟨font commands⟩ are executed at a very early stage in the construction of the node, the font selected using this command will also dictate the values of dimensions defined in terms of em or ex. For instance, when the minimum height of a node is 3em, the actual height will be (at least) three times the line distance selected by the ⟨font commands⟩:

A useful example of how the font option can be used is the following:

As can be seen, the font can be changed for each node part. This does not work with the node font command since, as the name suggests, this command can only be used to select the “overall” font for the node and this is done very early.

Setting ⟨dimension⟩ to an empty string causes the automatic line breaking to be disabled.

This key is used to set up an alignment for multi-line text inside a node. If text width is set to some width (let us call this alignment with line breaking), the align key will setup the \leftskip and the \rightskip in such a way that the text is broken and aligned according to ⟨alignment option⟩. If text width is not set (that is, set to the empty string; let us call this alignment without line breaking), then a different mechanism is used internally, namely the key node halign header, is set to an appropriate value. While this key, which is documented below, is not to be used by beginners, the net effect is simple: When text width is not set, you can use \\ to break lines and align them according to ⟨alignment option⟩ and the resulting node’s width will be minimal to encompass the resulting lines.

In detail, you can set ⟨alignment option⟩ to one of the following values:

• • align=left For alignment without line breaking, the different lines are simply aligned such that their left borders are below one another.

  

  copy
\tikz \node[fill=yellow!80!black,align=left]
{This is a\\ demonstration text for\\ alignments.};


  For alignment with line breaking, the same will happen; only the lines will now, additionally, be broken automatically:

  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=left]
{This is a demonstration text for showing how line breaking works.};


• • align=flush left For alignment without line breaking this option has exactly the same effect as left. However, for alignment with line breaking, there is a difference: While left uses the original plain TeX definition of a ragged right border, in which TeX will try to balance the right border as well as possible, flush left causes the right border to be ragged in the LaTeX-style, in which no balancing occurs. This looks ugly, but it may be useful for very narrow boxes and when you wish to avoid hyphenations.

  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=flush left]
{This is a demonstration text for showing how line breaking works.};


• • align=right Works like left, only for right alignment.

  

  copy
\tikz \node[fill=yellow!80!black,align=right]
{This is a\\ demonstration text for\\ alignments.};


  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=right]
{This is a demonstration text for showing how line breaking works.};


• • align=flush right Works like flush left, only for right alignment.

  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=flush right]
{This is a demonstration text for showing how line breaking works.};


• • align=center Works like left or right, only for centered alignment.

  

  copy
\tikz \node[fill=yellow!80!black,align=center]
{This is a\\ demonstration text for\\ alignments.};


  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=center]
{This is a demonstration text for showing how line breaking works.};


  There is one annoying problem with the center alignment (but not with flush center and the other options): If you specify a large line width and the node text fits on a single line and is, in fact, much shorter than the specified text width, an underfull horizontal box will result. Unfortunately, this cannot be avoided, due to the way TeX works (more precisely, I have thought long and hard about this and have not been able to figure out a sensible way to avoid this). For this reason, TikZ switches off horizontal badness warnings inside boxes with align=center. Since this will also suppress some “wanted” warnings, there is also an option for switching the warnings on once more:

  /tikz/badness warnings for centered text=⟨true or false⟩ (no default, initially false) ¶

  If set to true, normal badness warnings will be issued for centered boxes. Note that you may get annoying warnings for perfectly normal boxes, namely whenever the box is very large and the contents is not long enough to fill the box sufficiently.

• • align=flush center Works like flush left or flush right, only for center alignment. Because of all the trouble that results from the center option in conjunction with narrow lines, I suggest picking this option rather than center unless you have longer text, in which case center will give the typographically better results.

  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=flush center]
{This is a demonstration text for showing how line breaking works.};


• • align=justify For alignment without line breaking, this has the same effect as left. For alignment with line breaking, this causes the text to be “justified”. Use this only with rather broad nodes.

  

  copy
\tikz \node[fill=yellow!80!black,text width=3cm,align=justify]
{This is a demonstration text for showing how line breaking works.};


  In the above example, TeX complains (rightfully) about three very badly typeset lines. (For this manual I asked TeX to stop complaining by using \hbadness=10000, but this is a foul deed, indeed.)

• • align=none Disables all alignments and \\ will not be redefined.

You cannot just say node halign header=\hfil\hfil#\hfil\cr because this confuses TeX inside matrices, so this detour via a macro is needed.

Next, conceptually, all these boxes are recursively put inside an \halign command. Assuming that ⟨first⟩ is the first of the above boxes, the command \halign{⟨header⟩ \box⟨first⟩ \cr} is used to create a new box, which we will call the ⟨previous box⟩. Then, the following box is created, where ⟨second⟩ is the second input box: \halign{⟨header⟩ \box⟨previous box⟩ \cr \box⟨second⟩\cr}. Let us call the resulting box the ⟨previous box⟩ once more. Then the next box that is created is \halign{⟨header⟩ \box⟨previous box⟩ \cr \box⟨third⟩\cr}.

All of this means that if ⟨header⟩ is an \halign header like \hfil#\hfil\cr, then all boxes will be centered relative to one another. Similarly, a ⟨header⟩ of \hfil#\cr causes the text to be flushed right.

Note that this mechanism is not flexible enough to all multiple columns inside ⟨header⟩. You will have to use a tabular or a matrix in such cases.

One further note: Since the text of each line is placed in a box, settings will be local to each “line”. This is very similar to the way a cell in a tabular or a matrix behaves.

Sets the height of the text boxes in shapes. Thus, when you write something like node {text}, the text is first typeset, resulting in some box of a certain height. This height is then replaced by the height text height. The resulting box is then used to determine the size of the shape, which will typically be larger. When you write text height= without specifying anything, the “natural” size of the text box remains unchanged.

Causes the node to be shifted such that its anchor ⟨anchor name⟩ lies on the current coordinate.

The only anchor that is present in all shapes is center. However, most shapes will at least define anchors in all “compass directions”. Furthermore, the standard shapes also define a base anchor, as well as base west and base east, for placing things on the baseline of the text.

The standard shapes also define a mid anchor (and mid west and mid east). This anchor is half the height of the character “x” above the base line. This anchor is useful for vertically centering multiple nodes that have different heights and depth. Here is an example:

Similar to above.

Similar to above.

Similar to above.

Does the same as anchor=south east. Note that giving both above and left options does not have the same effect as above left, rather only the last left “wins”. Actually, this option also takes an ⟨offset⟩ parameter, but using this parameter without using the positioning library is deprecated. (The positioning library changes the meaning of this parameter to something more sensible.)

Similar to above left.

Similar to above left.

Similar to above left.

\usetikzlibrary{positioning} % LaTeX and plain TeX
\usetikzlibrary[positioning] % ConTeXt

The library defines additional options for placing nodes conveniently. It also redefines the standard options like above so that they give you better control of node placement.

With the positioning library loaded, the above option does not take a simple ⟨dimension⟩ as its parameter. Rather, it can (also) take a more elaborate ⟨specification⟩ as parameter. This ⟨specification⟩ has the following general form: It starts with an optional ⟨shifting part⟩ and is followed by an optional ⟨of-part⟩. Let us start with the ⟨shifting part⟩, which can have three forms:

• 1. It can simply be a ⟨dimension⟩ (or a mathematical expression that evaluates to a dimension) like 2cm or 3cm/2+4cm. In this case, the following happens: the node’s anchor is set to south and the node is vertically shifted upwards by ⟨dimension⟩.

  

  copy
\begin{tikzpicture}
\draw[help lines] (0,0) grid (2,2);
\node at (1,1) [above=2pt+3pt,draw] {above};
\end{tikzpicture}


  This use of the above option is the same as if the positioning library were not loaded.

• 2. It can be a ⟨number⟩ (that is, any mathematical expression that does not include a unit like pt or cm). Examples are 2 or 3+sin(60). In this case, the anchor is also set to south and the node is vertically shifted by the vertical component of the coordinate (0,⟨number⟩).

  

  copy
\begin{tikzpicture}
\draw[help lines] (0,0) grid (2,2);
\node at (1,1) [above=.2,draw] {above};
% south border of the node is now 2mm above (1,1)
\end{tikzpicture}


• 3. It can be of the form ⟨number or dimension 1⟩ and ⟨number or dimension 2⟩. This specification does not make particular sense for the above option, it is much more useful for options like above left. The reason it is allowed for the above option is that it is sometimes automatically used, as explained later.

  The effect of this option is the following. First, the point (⟨number or dimension 2⟩,⟨number or dimension 1⟩) is computed (note the inverted order), using the normal rules for evaluating such a coordinate, yielding some position. Then, the node is shifted by the vertical component of this point. The anchor is set to south.

  

  copy \usetikzlibrary {positioning}
\begin{tikzpicture}
\draw[help lines] (0,0) grid (2,2);
\node at (1,1) [above=.2 and 3mm,draw] {above};
% south border of the node is also 2mm above (1,1)
\end{tikzpicture}


The ⟨shifting part⟩ can optionally be followed by a ⟨of-part⟩, which has one of the following forms:

• 1. The ⟨of-part⟩ can be of ⟨coordinate⟩, where ⟨coordinate⟩ is not in parentheses and it is not just a node name. An example would be of somenode.north or of {2,3}. In this case, the following happens: First, the node’s at parameter is set to the ⟨coordinate⟩. Second, the node is shifted according to the ⟨shift-part⟩. Third, the anchor is set to south.

  Here is a basic example:

  

  copy \usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style=draw]
\draw[help lines] (0,0) grid (2,2);
\node (somenode) at (1,1) {some node};

\node [above=5mm of somenode.north east] {\tiny 5mm of somenode.north east};
\node [above=1cm of somenode.north] {\tiny 1cm of somenode.north};
\end{tikzpicture}


  As can be seen the above=5mm of somenode.north east option does, indeed, place the node 5mm above the north east anchor of somenode. The same effect could have been achieved writing above=5mm followed by at=(somenode.north east).

  If the ⟨shifting-part⟩ is missing, the shift is not zero, but rather the value of the node distance key is used, see below.

• 2. The ⟨of-part⟩ can be of ⟨node name⟩. An example would be of somenode. In this case, the following usually happens:

  • • The anchor is set to south.

  • • The node is shifted according to the ⟨shifting part⟩ or, if it is missing, according to the value of node distance.

  • • The node’s at parameter is set to ⟨node name⟩.north.

  The net effect of all this is that the new node will be placed in such a way that the distance between its south border and ⟨node name⟩’s north border is exactly the given distance.

  

  copy \usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style=draw]
\draw[help lines] (0,0) grid (2,2);
\node (some node) at (1,1) {some node};

\node (other node) [above=1cm of some node] {\tiny above=1cm of some node};

\draw [<->] (some node.north) -- (other node.south)
node [midway,right,draw=none] {1cm};
\end{tikzpicture}


  It is possible to change the behavior of this ⟨specification⟩ rather drastically, using the following key:

  /tikz/on grid=⟨boolean⟩ (no default, initially false) ¶

  When this key is set to true, an ⟨of-part⟩ of the current form behaves differently: The anchors set for the current node as well as the anchor used for the other ⟨node name⟩ are set to center.

  This has the following effect: When you say above=1cm of somenode with on grid set to true, the new node will be placed in such a way that its center is 1cm above the center of somenode. Repeatedly placing nodes in this way will result in nodes that are centered on “grid coordinate”, hence the name of the option.

  

  copy \usetikzlibrary {positioning}
\begin{tikzpicture}[every node/.style=draw]
\draw[help lines] (0,0) grid (2,3);

% Not gridded
\node (a1) at (0,0) {not gridded};
\node (b1) [above=1cm of a1] {fooy};
\node (c1) [above=1cm of b1] {a};

% gridded
\node (a2) at (2,0) {gridded};
\node (b2) [on grid,above=1cm of a2] {fooy};
\node (c2) [on grid,above=1cm of b2] {a};
\end{tikzpicture}


This key is redefined in the same manner as above.

This key is redefined in the same manner as above, only all vertical shifts are replaced by horizontal shifts.

This key is redefined in the same manner as left.

This key is also redefined in a manner similar to the above, but behavior of the ⟨shifting part⟩ is more complicated:

• 1. When the ⟨shifting part⟩ is of the form ⟨number or dimension⟩ and ⟨number or dimension⟩, it has (essentially) the effect of shifting the node vertically upwards by the first ⟨number or dimension⟩ and to the left by the second. To be more precise, the coordinate (⟨second number or dimension⟩,⟨first number or dimension⟩) is computed and then the node is shifted vertically by the \(y\)-part of the resulting coordinate and horizontally be the negated \(x\)-part of the result. (This is exactly what you expect, except possibly when you have used the x and y options to modify the xy-coordinate system so that the unit vectors no longer point in the expected directions.)

• 2. When the ⟨shifting part⟩ is of the form ⟨number or dimension⟩, the node is shifted by this ⟨number or dimension⟩ in the direction of \(135^\circ \). This means that there is a difference between a ⟨shifting part⟩ of 1cm and of 1cm and 1cm: In the second case, the node is shifted by 1cm upward and 1cm to the left; in the first case it is shifted by \(\frac {1}{2}\sqrt {2}\)cm upward and by the same amount to the left. A more mathematical way of phrasing this is the following: A plain ⟨dimension⟩ is measured in the \(l_2\)-norm, while a ⟨dimension⟩ and ⟨dimension⟩ is measured in the \(l_1\)-norm.

The following example should help to illustrate the difference:

Works similar to above left.

Works similar to above left.

Works similar to above left.

Works like base left.

Works like base left, but with mid east and mid west anchors instead of base east and base west.

When set to true, TikZ will try to apply any current nonlinear transformation also to nodes. Typically, for the text in nodes this is not possible in general, in such cases a linear approximation of the nonlinear transformation is used. For more details, see Section 108.4.

When this option is given, the node is not anchored on the last coordinate. Rather, it is anchored on some point on the line from the previous coordinate to the current point. The ⟨fraction⟩ dictates how “far” on the line the point should be. A ⟨fraction⟩ of 0 is the previous coordinate, 1 is the current one, everything else is in between. In particular, 0.5 is the middle.

Now, what is “the previous line”? This depends on the previous path construction operation.

In the simplest case, the previous path operation was a “line-to” operation, that is, a --⟨coordinate⟩ operation:

For the arc operation, the position is simply the corresponding position on the arc:

The next case is the curve-to operation (the .. operation). In this case, the “middle” of the curve, that is, the position 0.5 is not necessarily the point at the exact half distance on the line. Rather, it is some point at “time” 0.5 of a point traveling from the start of the curve, where it is at time 0, to the end of the curve, which it reaches at time 0.5. The “speed” of the point depends on the length of the support vectors (the vectors that connect the start and end points to the control points). The exact math is a bit complicated (depending on your point of view, of course); you may wish to consult a good book on computer graphics and Bézier curves if you are intrigued.

Another interesting case are the horizontal/vertical line-to operations |- and -|. For them, the position (or time) 0.5 is exactly the corner point.

For all other path construction operations, the position placement does not work, currently.

This option causes an anchor position to be calculated automatically according to the following rule. Consider a line between two points. If the ⟨direction⟩ is left, then the anchor is chosen such that the node is to the left of this line. If the ⟨direction⟩ is right, then the node is to the right of this line. Leaving out ⟨direction⟩ causes automatic placement to be enabled with the last value of left or right used. A ⟨direction⟩ of false disables automatic placement. This happens also whenever an anchor is given explicitly by the anchor option or by one of the above, below, etc. options.

This option only has an effect for nodes that are placed on lines or curves.

This is a very short alias for swap.

This option causes the node to be rotated such that a horizontal line becomes a tangent to the curve. The rotation is normally done in such a way that text is never “upside down”. To get upside-down text, use can use [rotate=180] or [allow upside down], see below.