tikz.dev / tikz-cd Manual
\(\newcommand{\footnotename}{footnote}\) \(\def \LWRfootnote {1}\) \(\newcommand {\footnote }[2][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\newcommand {\footnotemark }[1][\LWRfootnote ]{{}^{\mathrm {#1}}}\) \(\let \LWRorighspace \hspace \) \(\renewcommand {\hspace }{\ifstar \LWRorighspace \LWRorighspace }\) \(\newcommand {\TextOrMath }[2]{#2}\) \(\newcommand {\mathnormal }[1]{{#1}}\) \(\newcommand \ensuremath [1]{#1}\) \(\newcommand {\LWRframebox }[2][]{\fbox {#2}} \newcommand {\framebox }[1][]{\LWRframebox } \) \(\newcommand {\setlength }[2]{}\) \(\newcommand {\addtolength }[2]{}\) \(\newcommand {\setcounter }[2]{}\) \(\newcommand {\addtocounter }[2]{}\) \(\newcommand {\arabic }[1]{}\) \(\newcommand {\number }[1]{}\) \(\newcommand {\noalign }[1]{\text {#1}\notag \\}\) \(\newcommand {\cline }[1]{}\) \(\newcommand {\directlua }[1]{\text {(directlua)}}\) \(\newcommand {\luatexdirectlua }[1]{\text {(directlua)}}\) \(\newcommand {\protect }{}\) \(\def \LWRabsorbnumber #1 {}\) \(\def \LWRabsorbquotenumber "#1 {}\) \(\newcommand {\LWRabsorboption }[1][]{}\) \(\newcommand {\LWRabsorbtwooptions }[1][]{\LWRabsorboption }\) \(\def \mathchar {\ifnextchar "\LWRabsorbquotenumber \LWRabsorbnumber }\) \(\def \mathcode #1={\mathchar }\) \(\let \delcode \mathcode \) \(\let \delimiter \mathchar \) \(\def \oe {\unicode {x0153}}\) \(\def \OE {\unicode {x0152}}\) \(\def \ae {\unicode {x00E6}}\) \(\def \AE {\unicode {x00C6}}\) \(\def \aa {\unicode {x00E5}}\) \(\def \AA {\unicode {x00C5}}\) \(\def \o {\unicode {x00F8}}\) \(\def \O {\unicode {x00D8}}\) \(\def \l {\unicode {x0142}}\) \(\def \L {\unicode {x0141}}\) \(\def \ss {\unicode {x00DF}}\) \(\def \SS {\unicode {x1E9E}}\) \(\def \dag {\unicode {x2020}}\) \(\def \ddag {\unicode {x2021}}\) \(\def \P {\unicode {x00B6}}\) \(\def \copyright {\unicode {x00A9}}\) \(\def \pounds {\unicode {x00A3}}\) \(\let \LWRref \ref \) \(\renewcommand {\ref }{\ifstar \LWRref \LWRref }\) \( \newcommand {\multicolumn }[3]{#3}\) \(\require {textcomp}\) \(\newcommand {\meta }[1]{\langle \textit {#1}\rangle }\) \(\newcommand {\intertext }[1]{\text {#1}\notag \\}\) \(\let \Hat \hat \) \(\let \Check \check \) \(\let \Tilde \tilde \) \(\let \Acute \acute \) \(\let \Grave \grave \) \(\let \Dot \dot \) \(\let \Ddot \ddot \) \(\let \Breve \breve \) \(\let \Bar \bar \) \(\let \Vec \vec \)

1Getting started

To load this package in , type

  • \usepackage{tikz-cd}

or load TikZ and then type

  • \usetikzlibrary{cd}

This package is compatible with other formats as well. See §1.5 and §1.6.

1.1Creating a diagram

The basic tool to create a commutative diagram is the following environment.

  • \begin{tikzcd}[⟨options⟩]

  • ⟨environment contents⟩

  • \end{tikzcd}

The environment contents should describe a matrix, as in ’s familiar {tabular} environment. The optional argument ⟨options⟩ may be used to modify the appearance of the diagram. Any of the customization keys described in this manual, as well as those originally provided by TikZ, can be used here. Arrows between matrix entries can be created with the \arrow command described below.

Everything inside {tikzcd} is typeset in math mode, but you will probably want to use it inside an {equation} environment or \[ …\], so that the diagram is placed on a new line and centered.

It is important to note that dvi viewers will not display diagrams correctly. It is necessary to convert the dvi file to pdf or ps format—or, even better, use a tool that generates pdf files directly, such as pdflatex.

1.2Inserting arrows

Inside the {tikzcd} environment, the following synonymous commands are provided to produce arrows.

  • \arrow[⟨options⟩]

  • \ar[⟨options⟩]

Here, ⟨options⟩ is a comma-separated list of options which can be used to specify the arrow target, add labels, change arrow tips, and perform additional modifications.

The arrow target can be specified by a direction parameter, which consists of a string of characters r, l, d, u (standing for right, left, down and up). Labels can be placed on an arrow by means of the quotes syntax, described in detail in the pgf manual [2, label quotes]. Notice the use of "\phi" in the example below.

(-tikz- diagram)

\begin{tikzcd}
A \arrow[rd] \arrow[r, "\phi"] & B \\
& C
\end{tikzcd}

To further modify the appearance of an arrow, note that ⟨options⟩ may contain any key that can be passed to TikZ’s \path command. Similarly, a label can receive additional options via the syntax

  • "⟨label text⟩"⟨label options⟩.

Both ⟨label text⟩ and ⟨label options⟩ need to be enclosed in curly braces if they contain commas.

(-tikz- diagram)

\begin{tikzcd}
A \arrow[r, "\phi"] \arrow[d, red]
& B \arrow[d, "\psi" red] \\
C \arrow[r, red, "\eta" blue]
& |[blue, rotate=-15]| D
\end{tikzcd}

The example above also showcases one of the possible ways to pass special options to a TikZ matrix node. See the pgf manual [2, matrices] for more information.

Arrows can have an arbitrary number of labels, by repeated use of arguments in quotes. The example below shows how to control the positioning of labels. Notice in particular that an apostrophe as ⟨label option⟩ causes the label to be placed on the opposite side of the arrow.

(-tikz- diagram)

\begin{tikzcd}
A \arrow[r, "\phi" near start, "\psi"', "\eta" near end] & B
\end{tikzcd}

We provide two real-life examples.

(-tikz- diagram)

\begin{tikzcd}
T
\arrow[drr, bend left, "x"]
\arrow[ddr, bend right, "y"]
\arrow[dr, dotted, "{(x,y)}" description] & & \\
& X \times_Z Y \arrow[r, "p"] \arrow[d, "q"]
& X \arrow[d, "f"] \\
& Y \arrow[r, "g"]
& Z
\end{tikzcd}

(-tikz- diagram)

\begin{tikzcd}[column sep=tiny]
& \pi_1(U_1) \ar[dr] \ar[drr, "j_1", bend left=20]
&
&[1.5em] \\
\pi_1(U_1\cap U_2) \ar[ur, "i_1"] \ar[dr, "i_2"']
&
& \pi_1(U_1) \ast_{ \pi_1(U_1\cap U_2)} \pi_1(U_2) \ar[r, dashed, "\simeq"]
& \pi_1(X) \\
& \pi_1(U_2) \ar[ur]\ar[urr, "j_2"', bend right=20]
&
&
\end{tikzcd}
1.3Changing arrow tips

A set of \arrow options is provided to create different kinds of arrows. Some of these options have a short descriptive name, such as hook, and others are named after arrow-producing commands (without a “\”), like dashrightarrow.

(-tikz- diagram)

\begin{tikzcd}
X \arrow[r, hook] \arrow[dr, dashrightarrow]
& \bar{X} \arrow[d]\\
& Y
\end{tikzcd}

The following list shows all available arrow types (each of them is a style key located in /tikz/commutative diagrams).

Basic arrows
.
to head yields (-tikz- diagram)
rightarrow yields (-tikz- diagram)
leftarrow yields (-tikz- diagram)
leftrightarrow yields (-tikz- diagram)
Rightarrow yields (-tikz- diagram)
Leftarrow yields (-tikz- diagram)
Leftrightarrow yields (-tikz- diagram)
Arrows from bar
.
maps to yields (-tikz- diagram)
mapsto yields (-tikz- diagram)
mapsfrom yields (-tikz- diagram)
Mapsto yields (-tikz- diagram)
Mapsfrom yields (-tikz- diagram)
Arrows with hook
.
hook yields (-tikz- diagram)
hook' yields (-tikz- diagram)
hookrightarrow yields (-tikz- diagram)
hookleftarrow yields (-tikz- diagram)
Arrows with tail
.
tail yields (-tikz- diagram)
rightarrowtail yields (-tikz- diagram)
leftarrowtail yields (-tikz- diagram)
Two-headed arrows
.
two heads yields (-tikz- diagram)
twoheadrightarrow yields (-tikz- diagram)
twoheadleftarrow yields (-tikz- diagram)
Harpoons
.
harpoon yields (-tikz- diagram)
harpoon' yields (-tikz- diagram)
rightharpoonup yields (-tikz- diagram)
rightharpoondown yields (-tikz- diagram)
leftharpoonup yields (-tikz- diagram)
leftharpoondown yields (-tikz- diagram)
Dashed arrows
.
dashed yields (-tikz- diagram)
dashrightarrow yields (-tikz- diagram)
dashleftarrow yields (-tikz- diagram)
Squiggly arrows
.
squiggly yields (-tikz- diagram)
rightsquigarrow yields (-tikz- diagram)
leftsquigarrow yields (-tikz- diagram)
leftrightsquigarrow yields (-tikz- diagram)
Non-arrows
.
no head yields (-tikz- diagram)
no tail yields (-tikz- diagram)
dash yields (-tikz- diagram)
equal yields (-tikz- diagram)

A gray cross ( (-tikz- diagram)) in the samples above indicates that the corresponding tip is kept unchanged. This allows several arrow styles to be superimposed.

(-tikz- diagram)

\begin{tikzcd}
A \arrow[r, tail, two heads, dashed] & B
\end{tikzcd}
1.4Alternative syntax for arrows

The following forms of the arrow command were used before the appearance of the quotes syntax for labels, and now may seem somewhat convoluted. They are nonetheless still available for backwards compatibility.

  • \arrow[⟨options⟩]{⟨direction⟩}⟨labels⟩

Here, ⟨direction⟩ is a string containing the characters r, l, d, u and is used to determine the arrow target. Alternatively, you can specify an explicit matrix cell by replacing ⟨direction⟩ with something of the form ⟨row number⟩-⟨column number⟩, or the name of a node. The trailing ⟨labels⟩ can be the empty string or of the form

  • [⟨label options⟩]{⟨label text⟩}⟨more labels⟩.

The equivalent command \ar can also be used in this form. Here is an example.

(-tikz- diagram)

\begin{tikzcd}
A \arrow{d} \arrow{r}[near start]{\phi}[near end]{\psi}
& B \arrow[red]{d}{\xi} \\
C \arrow[red]{r}[blue]{\eta}
& D
\end{tikzcd}

There are further shortened forms:

  • \rar[⟨options⟩]⟨labels⟩

  • \lar[⟨options⟩]⟨labels⟩

  • \dar[⟨options⟩]⟨labels⟩

  • \uar[⟨options⟩]⟨labels⟩

  • \drar[⟨options⟩]⟨labels⟩

  • \urar[⟨options⟩]⟨labels⟩

  • \dlar[⟨options⟩]⟨labels⟩

  • \ular[⟨options⟩]⟨labels⟩

The first one is equivalent to

  • \arrow[⟨options⟩]{r}⟨labels⟩

and the other ones work analogously.

1.5Usage in plain

To use this package in plain , load TikZ and the cd library by saying

  • \input tikz.tex
    \usetikzlibrary{cd}

The {tikzcd} environment should then be replaced by the following:

  • \tikzcd[⟨options⟩]

  • ⟨environment contents⟩

  • \endtikzcd

All other functions of this library work as described in this manual without change.

1.6Usage in Cont

To use this package in Cont, load TikZ and then the cd library by saying

  • \usemodule[tikz]
    \usetikzlibrary[cd]

The {tikzcd} environment should then be replaced by the following:

  • \starttikzcd[⟨options⟩]

  • ⟨environment contents⟩

  • \stoptikzcd

Moreover, you may replace the column and row separators &, \\ by their Cont analogues \NC, \NR. However, you should use \NC only between cells, and not before the first column or after the last column, as in usual Cont tables. Similarly, \NR should be used only between rows.

All other functions of this library work as described in this manual without change.