Cleveref, a clever way to reference in LaTeX

20 Comments

Using standard cross-referencing in LaTeX only produces the label number, a name describing the label such as figure, chapter or equation has to be added manually. The cleveref package overcomes this limitation by automatically producing the label name and number. It further allows cross-referencing ranges of labels and multiple labels of the same or different kinds, including auto-sorting and compression of labels.

 

Basic cross-reference command

Cleveref implements \cref for basic cross-referencing. The command is used in the same way as the standard \ref command. Besides the label number it also produces the reference kind.

Warning: <strong>cleverref</strong> has to be loaded after <strong>hyperref</strong>!

Here is an example:

basic-cleveref

\documentclass[11pt]{article}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{cleveref}
\begin{document}

\begin{align}
y&=a_1x+b_1\label{eqn:1}
\end{align}

\noindent
Standard equation reference (\textbackslash ref): \ref{eqn:1}\\
Cleveref equation reference (\textbackslash cref): \cref{eqn:1}

\begin{figure}[ht]\centering\rule{0.5\linewidth}{0.1\linewidth}\caption{First figure}\label{fig:1}\end{figure}

\noindent
Standard figure reference (\textbackslash ref): \ref{fig:1}\\
Cleveref figure reference (\textbackslash cref): \cref{fig:1}

\end{document}

 

Multiple labels (sort and compress)

To cross-reference multiple labels of the same or different kinds, the \cref command is used. Labels are separated by commas without white-space (\cref{ref1,ref2,etc.}). For a range of the same label kind, the command \crefrange{first}{last} is available.

range-mixed-cleveref

\documentclass[11pt]{article}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{cleveref}

\begin{document}

\begin{align}
y&=a_1x+b_1\label{eqn:1}\\
y&=a_2x+b_2\label{eqn:2}\\
y&=a_3x+b_3\label{eqn:3}\\
y&=a_4x+b_4\label{eqn:4}
\end{align}

\noindent
Range example: \crefrange{eqn:1}{eqn:4}

\begin{figure}[ht]\centering\rule{0.5\linewidth}{0.1\linewidth}\caption{First figure}\label{fig:1}\end{figure}

\noindent
Mixed references example: \cref{eqn:1,eqn:3,eqn:4,fig:1}

\end{document}

 

Capitalize at beginning of sentence

By default, label names are produced with a small initial letter. To capitalize the first letter at the beginning of a sentence, use \Cref and \Crefrange instead.

For capitalization of all label names throughout the document, load the package with the capitalise option.

\usepackage[capitalise]{cleveref}

 

Full label names

If you prefer to use the full label name rather than abbreviations such as fig. or eq., load the package with the noabbrev option:

\usepackage[noabbrev]{cleveref}

 

Clickable references with hyperref

The cleveref package is fully compatible with hyperref (package manual). It is important to load the cleveref package last, after hyperref.

% Preamble
\usepackage{...} % other packages
\usepackage{hyperref}
\usepackage{cleveref}

\begin{document}
...

 

Other features of the package

The cleveref package offers a lot more, including:

  • Customization of labels
  • Name-only references
  • Page number of label
  • and more…

See the package documentation for more details.

 

Alternative packages

There are a number of packages implementing similar features. According to the documentation, cleveref is among the most extensive in terms of functionality and flexibility. However, through a recently published post on LaTeX Alive I learnt that the refstyle package is a valid alternative to cleveref and I’ll definitely give it a try.

20 Comments

  1. Good morning,

    As soon as I saw that, I thought “how cool”. So, I went to the paper I am working on now, and added \usepackage{cleveref}, replaced all \ref by \cref, and compiled but it didn’t work: all references where now “??”. So, I deleted all the aux files, and tried again, but it still didn’t work. Therefore, this doesn’t work for me. Any idea why?

    Reply

    • Hi Guillaume,

      Thanks for your comment. It’s all there in bold, under “Clickable references with hyperref”.

      Cheers, Tom

      Reply

      • Hi Tom,

        I found out something else: the references didn’t work properly for the figures until I figured out that I needed to put the label inside the caption. Otherwise, I put the number of the section instead of the figure. I tried to put the label right at the start, right at the end, in the \centre, before the caption, and nothing worked other than putting it inside the cation. Maybe this is only the case with the emulateapj document class, but in any case, it might be useful to some other astrophysicist that reads your blog.

  3. Hi Tom: Did you, by any chance, have time to look into why \cref for sections doesn’t work in emulateapj.cls? A fix for this would be great. Ciao. Guillaume

    Reply

    • tom

      Hi Guillaume,

      I downloaded the emulateapj class file and used it with the multiple labels example above. In the example, \label is outside \caption. The example works for me as long as I use \label after \caption.

      If this doesn’t solve your problem, please provide a minimal working example and I’ll look into it.

      Thanks, Tom

      Reply

      • Hi Tom. Thanks a lot for looking into it. The problem is not for Figures; that works for me (with label outside the caption). It’s for Section; it gives ?? instead of the ref. Here is my min “working” example where I have stripped the paper I’m working on now to leave only the relevant bits.

        \begin{document}

\title{Towards Unifying Time Domain Astronomy}
\shorttitle{Towards Unifying Time Domain Astronomy}

\author{G.\ B\'elanger}
\affil{European Space Astronomy Centre (ESA/ESAC), Science Operations Department, \\ Villanueva de la Ca\~nada (Madrid), Spain; \\ \href{mailto:gbelanger@sciops.esa.int}{gbelanger@sciops.esa.int}}

\begin{abstract}
Time domain astronomy concerns itself with the study of astrophysical systems by characterising the properties of the light they emit in order to deduce and infer something about the physical mechanisms that could be responsible for giving rise to this emission.
\end{abstract}
\keywords{methods: data analysis -- methods: statistical}

\section{Introduction}

The task is divided in three the categories mentioned earlier, which relate to the characterisation of constance, which also includes searching for new or transient sources (Section \ref{s:constancy}); periodicity at any scale and whatever the nature (\cref{s:periodicity}); and stochastic variability, including the tracing and detection of state changes (\cref{s:variability}).

\section{Characterising Constancy}
\label{s:constancy}

\section{Characterising Periodicity}
\label{s:periodicity}

\section{Characterising Stochastic Variability}
\label{s:variability}

\end{document}

      • tom

        Hi Guillaume,

        After trying for some time, I don’t think I’ll be able to come up with a solution within a reasonable amount of time. If the problem only occurs for sections, you might just want to define your own command:

        \newcommand\sref[1]{Section \ref{#1}}

        If you rather use the cleveref package, consider submitting your question to tex.SX.

        Best, Tom

  5. Nice write up.

    I’m obviously biased, but `refstyle` is not a `cleveref` rival in any meaningful sense. As I understand, it provides a series of \eqref, \figref, \secref etc. commands for produces cross-references to equations, figures, sections, etc. It doesn’t automatically detect the type of thing you’re references and format it appropriately. So you have to use one command for referencing equations, a different one for figures, yet another for sections etc. This might save a few characters of typing (“\figref” instead of “Figure~\ref”), but not much else. Even the old `smartref` package does something more sophisticated.

    And that’s not to mention all the other `cleveref` features that have no equivalent in `refstyle` (e.g. multi-references).

    Reply

    • tom

      Thanks for your comment and for creating this invaluable package! Would you be interested in writing a guest post here, possibly discussing some more advanced features of your package?

      Best wishes, Tom

      Reply

  6. Kerina

    1. Is it possible to use only cleveref (and not use hyperref at all)?

    2. Does cleveref have any problems with polyglossia (like hyperref does with polyglossia)?

    Thanx.

    Reply

  7. Hello Tom,

    Thanks for your informative post.

    I would like to know something; how can I make the whole cross-reference (label and number) a clickable link not just the number?

    Thanks

    Reply

Leave a Reply