Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Cross-references and Bibliographies

Labels and Cross-references

Number sections, figures, tables and equations automatically, then refer to them with \label, \ref, \eqref, \pageref and cleveref, without ever typing a number.

In a long document, numbers change all the time. You add a figure, a section moves, an equation is deleted, and every sentence that says "see Figure 3" is suddenly wrong. LaTeX solves this by letting you attach a label to a thing and then refer to that label by name. LaTeX looks up the current number for you.

This lesson covers the label and reference commands, the two-pass way LaTeX resolves them, the rules for putting a label in the right place, and the cleveref package that writes words such as "Figure" or "Section" for you.

The basic pair: \label and \ref

\label{key} stores the number of the nearest numbered thing before it. \ref{key} prints that number. \pageref{key} prints the page number.

LATEX
\section{Methods}\label{sec:methods}

We describe the setup in Section~\ref{sec:methods}.
The result appears on page~\pageref{fig:result}.

\begin{figure}[ht]
  \centering
  \includegraphics[width=0.6\textwidth]{result.pdf}
  \caption{The measured response.}\label{fig:result}
\end{figure}

Figure~\ref{fig:result} shows the response.

Three habits make this reliable:

  • Use a tilde before the reference. Section~\ref{...} inserts a non-breaking space, so the word "Section" is never separated from its number at a line break.
  • Use a prefix in the key. Conventions such as sec:, fig:, tab:, eq: and chap: make keys easy to find and avoid clashes.
  • Keys are case-sensitive and may not contain spaces or special characters such as %, # or \. Letters, digits, colons, hyphens and dots are safe.

Where the label goes

A label records the value of the most recent counter that was stepped. That is why placement matters:

Thing Put \label
Section, chapter Right after \section{...}
Figure or table After \caption{...} (the caption steps the counter)
Equation Inside the equation environment
List item Right after \item
Theorem Inside the environment, after the heading

The most common mistake is placing \label before \caption. The label then captures the section number instead of the figure number, and your reference prints "2" when it should print "1".

LATEX
% Wrong: label captures the section counter
\begin{figure}
  \label{fig:bad}
  \caption{A caption}
\end{figure}

% Right: the caption steps the figure counter first
\begin{figure}
  \caption{A caption}
  \label{fig:good}
\end{figure}

Why you compile twice

LaTeX reads your file from top to bottom once. When it reaches \ref{sec:methods} early in the file, the section has not been seen yet, so it cannot know the number. The solution is a two-pass process:

  1. First run. LaTeX typesets the document, and whenever it meets \label it writes key -> number into an auxiliary file named main.aux. Unknown references print as ?? and LaTeX warns Reference ... undefined.
  2. Second run. LaTeX reads main.aux at the start and now every \ref has a value.

Sometimes a third run is needed: inserting a reference can change the page layout, which shifts a page number that another reference already printed. Tools such as latexmk repeat the runs until the numbers stop changing (see engines, latexmk and errors).

The stand-in below mimics this behaviour. It stores labels in a table on the first pass and resolves them on the second.

JS Two-pass reference resolution

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that fig:missing still prints ?? on the second run. That is exactly how LaTeX reports a label that does not exist: after a clean build, any remaining ?? is a typo.

Equations, \eqref and \pageref

For equations the amsmath package provides \eqref, which wraps the number in parentheses automatically:

LATEX
\usepackage{amsmath}
...
\begin{equation}\label{eq:energy}
  E = mc^2
\end{equation}

Equation~\eqref{eq:energy} relates mass and energy.

This prints "Equation (1) relates mass and energy." Do not write (\ref{eq:energy}) by hand; \eqref also takes care of italic correction so the parentheses stay upright.

\pageref{key} is handy for printed documents: "see the table on page~\pageref{tab:data}". For a PDF read on screen the page number is less useful, so combine it with hyperlinks.

Clickable references with hyperref

Loading hyperref turns every \ref, citation and table-of-contents entry into a clickable link in the PDF:

LATEX
\usepackage[colorlinks=true, linkcolor=blue, citecolor=darkgray]{hyperref}

Two rules apply. First, load hyperref near the end of your preamble because it redefines many internal commands; the main exceptions are cleveref, which must come after it. Second, use \autoref{key} if you want the word added for you: \autoref{fig:result} prints "Figure 1" with the whole phrase clickable.

cleveref: let LaTeX write the word

cleveref goes further. \cref{key} prints both the type name and the number, and it can combine several keys.

LATEX
\usepackage{hyperref}
\usepackage[capitalise,noabbrev]{cleveref} % load after hyperref

\cref{sec:methods}                 % section 1
\Cref{fig:plot}                    % Figure 2 (capitalised at sentence start)
\cref{fig:a,fig:b,fig:c}           % figures 1, 2 and 3 (merged range)
\cref{eq:energy}                   % equation (1)

With cleveref you never type "Figure" or "Section", so changing the style (for example to "Fig.") is a one-line change in the preamble.

Troubleshooting references

  • ?? in the output: compile again; if it stays, check for a typo in the key.
  • "Label multiply defined": two \label commands share a key. Rename one.
  • Wrong number: the label sits before the thing it should follow (see the table above).
  • References inside \section{...} titles break the table of contents: use \section[Short title]{Long title} and put labels after the command.
  • Stale numbers after editing: delete the .aux file (or run latexmk -C) and compile again.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a reference sometimes show ?? after the first compilation?

    LaTeX writes labels to the .aux file during one run and reads them at the start of the next, so a second compilation resolves forward references.
  2. 2. Where should \label go inside a figure environment?

    The caption steps the figure counter. A label placed before it records the previous counter value, so the reference shows the wrong number.
  3. 3. What does \eqref{eq:energy} print compared with \ref{eq:energy}?

    \eqref from amsmath wraps the equation number in parentheses automatically.
  4. 4. Which package prints the word and the number, for example Figure 2, from a single command?

    cleveref's \cref and \Cref add the type name for you, and can merge several keys into a range.

Summary

  • \label{key} records a counter value and \ref{key} prints it; \pageref prints the page.
  • Put the label after \caption, after \section, or inside the equation.
  • LaTeX needs two or more runs because labels go through the .aux file.
  • Use Section~\ref{...} with a tilde and prefixed keys such as fig: and tab:.
  • \eqref, hyperref's \autoref and cleveref's \cref save you from typing numbers and words.

Next: BibTeX Basics