# Difference between ref, varioref and cleveref. Decision for a thesis

How can one make a quick decision what the best "ref" for a thesis in pdflatex with hyperref is?

After a few hours reading I do not know more than

• ref is used by everyone who does not know about the other ~ref and works stable
• \vref varioref somehow works together with hyperref makes sometimes trouble with pagebreaks
• \cref in cleveref is still in beta(?) (edit: not in beta any more) and does the same like varioref

What are the essential questions that I have to ask myself to find out which method fits best?

• Nov 16, 2012 at 22:54
• Also, cleveref doesn't do the same as varioref. The former will try to figure what you're referencing, so \cref{fig:figure} can print e.g. Figure 1. varioref doesn't do this, but \vref{fig:figure} reference can print e.g. 1 on this page, or 1 on the preceding page. Only if the reference is more than two pages away, will the page number be printed, 1 on page 12. The two can be used together though, see the cleveref manual. Nov 16, 2012 at 23:02
• OK i thought the packages would compete each other Nov 16, 2012 at 23:12
• The cleveref package has been around for a number of years and can't be considered to be "in beta" at this point.
– Mico
Nov 20, 2012 at 20:23
• Someone should correct the Wikipedia article then where it is called "beta". Nov 21, 2012 at 1:24

You can certainly load both the varioref and the cleveref with hyperref provided that you load them in the following order

\usepackage{varioref}
\usepackage{hyperref}
\usepackage{cleveref}


They all play very nicely together.

The varioref and cleveref weren't around when I did my thesis, but I'm working on a multi-chapter document at the moment in which I'm using both. Here is what I have found to be a good workflow:

• at a minimum, use \cref and friends (from cleveref) in favour of \ref. This means that, for example, you never have to worry about if you have to capitalize Figure or figure when referencing a figure; instead of saying Figure \ref{fig:myfig} you just use \cref{fig:myfig}. Maybe you'll change your mind and end up using fig.; in which case you can make the change globally using \crefname and \Crefname
• use \vref and friends (from varioref) to refer to objects 'far away' from the current position in the text; my rule for the moment is to use \vref when referring to something in a different section. Some might say that this isn't very robust, but if the object you are referring to moves closer, \vref will still work fine. If you load cleveref then \vref becomes clever too, so you simply write \vref{fig:myfig}, not Figure \vref{fig:myfig}

The problems you describe with varioref occur if you allow hyperlinks to break, and the reference happens to break across a page that changes the reference from something like 'this page' to 'the next page'. In such a case, you'll have to tweak things manually- if you're using the work flow I've described above and only using \vref for 'far away' references and \cref for everything else, then this won't be an issue.

Here's a MWE to illustrate some of the features:

\documentclass{report}
\usepackage{varioref}
\usepackage{hyperref}
\usepackage{cleveref}

% each of the following has two versions
%   \crefname{environmentname}{singular}{plural}, to be used mid-sentence
%   \Crefname{environmentname}{singular}{plural}, to be used at the beginning of a sentence
\crefname{table}{table}{tables}
\Crefname{table}{Table}{Tables}
\crefname{figure}{figure}{figures}
\Crefname{figure}{Figure}{Figures}
\begin{document}

\begin{figure}[!htb]
\centering
\rule{20pt}{20pt}
\caption{My figure}
\label{fig:myfig}
\end{figure}

\clearpage
\begin{itemize}
\item Use \cref{fig:myfig} mid sentence.
\item \Cref{fig:myfig} is appropriate for the beginning of a sentence.
\item Use \vref{fig:myfig} mid sentence, note that it has become clever'.
\item \Vref{fig:myfig} is appropriate for the beginning of a sentence.
\end{itemize}
\end{document}


There are too many problems with varioref. Nobody has time to sort them out. Therefore this package is now unsupported.

In fact, as noted by @Mico in Lost labels using intertext with varioref and hyperref, loading the cleveref package in addition to varioref and hyperref seems to eliminate a lot of the problems, as cleveref redefines \vref and friends to make them clever.

• The 3rd item reads Use Figure 1 on the preceding I guess cref and vref should switch in the example, right? Nov 17, 2012 at 14:07
• @JonasStein that is a matter of personal preference, and precisely one of the reasons to use the cleveref :) however, since it's your question, I'll leave your edit :) Nov 17, 2012 at 16:22
• According to the hyperref README, the varioref package is not supported by the hyperref package due to various reasons. Doesn’t this apply any more?
– mhp
Nov 17, 2012 at 20:06
• @mhp - Loading the cleveref package (in addition to varioref and hyperref, of course) happens to eliminate the pesky little incompatibilities between varioref and hyperref. See tex.stackexchange.com/a/51640/5001 for more information on this.
– Mico
Nov 20, 2012 at 20:22
• @cmhughes Very nice answer, which is still up to date! One thing I'd like to mention: When referencing "larger" labeled items, such as chapters or sections, I generelly don't use \vref`. Imho references to sections etc should never contain page numbers. Mar 10, 2020 at 16:30