hyperref — Hyperlinks, Cross-References & PDF Metadata
CTAN: https://ctan.org/pkg/hyperref
Manual: texdoc hyperref
Setup
% LOAD HYPERREF LAST (or near last) — it redefines many commands
\usepackage[
colorlinks=true,
linkcolor=blue,
citecolor=green!50!black,
urlcolor=blue!70!black,
pdftitle={My Document Title},
pdfauthor={Author Name},
]{hyperref}
% If using cleveref, load it AFTER hyperref:
\usepackage{cleveref}
Common Setup Options
| Option | Default | Description |
|---|
colorlinks | false | Color link text (vs boxes) |
linkcolor | red | Internal links (refs, TOC) |
citecolor | green | Citation links |
urlcolor | magenta | URL links |
filecolor | cyan | File links |
allcolors | — | Set all link colors at once |
hidelinks | — | No color, no boxes (for print) |
bookmarks | true | Generate PDF bookmarks |
bookmarksnumbered | false | Include section numbers in bookmarks |
bookmarksopen | false | Expand bookmarks by default |
pdfborder | {0 0 1} | Link border (set {0 0 0} to remove) |
breaklinks | true | Allow links to break across lines |
unicode | true (modern) | Unicode in bookmarks |
PDF Metadata Options
| Option | Description |
|---|
pdftitle | Document title |
pdfauthor | Author name(s) |
pdfsubject | Subject |
pdfkeywords | Keywords (comma-separated) |
pdfcreator | Creating application |
pdfproducer | PDF producer |
% Or set after loading:
\hypersetup{
pdftitle={My Paper},
pdfauthor={Jane Doe},
pdfsubject={LaTeX Tutorial},
pdfkeywords={LaTeX, hyperref, tutorial},
}
Link Commands
% External URL
\href{https://example.com}{Click here}
\href{mailto:user@example.com}{Email me}
\href{file:./report.pdf}{Local file}
% URL (typewriter, breakable)
\url{https://example.com/path?query=value}
% Internal reference with custom text
\hyperref[sec:intro]{see the introduction}
% Standard cross-references (auto-linked by hyperref)
\ref{fig:plot} % "3"
\pageref{tab:data} % "12"
\eqref{eq:main} % "(1)" — from amsmath
% Auto-named references
\autoref{fig:plot} % "Figure 3"
\autoref{tab:data} % "Table 2"
\autoref{sec:intro} % "section 1"
\autoref{eq:main} % "equation 1"
% Name reference (prints the title/caption)
\nameref{sec:intro} % "Introduction"
\autoref Names
| Counter | Default name |
|---|
figure | Figure |
table | Table |
equation | equation |
section | section |
chapter | chapter |
theorem | Theorem |
page | page |
Customize: \renewcommand{\sectionautorefname}{Section}
cleveref Integration
\usepackage{hyperref}
\usepackage{cleveref} % MUST be after hyperref
% Automatic type detection + ranges
\cref{fig:a} % "fig. 1"
\Cref{fig:a} % "Figure 1" (capitalized)
\cref{fig:a,fig:b,fig:c} % "figs. 1 to 3"
\cref{eq:1,eq:2} % "eqs. (1) and (2)"
\crefrange{fig:a}{fig:d} % "figs. 1 to 4"
% Customize names
\crefname{equation}{eq.}{eqs.}
\Crefname{equation}{Equation}{Equations}
\crefname{figure}{fig.}{figs.}
Bookmarks
% Manual bookmark entry
\pdfbookmark[level]{Text}{anchor}
\pdfbookmark[0]{Title Page}{title}
% Current bookmark (without section command)
\currentpdfbookmark{Appendix A}{appendixA}
% Bookmark with section:
\belowpdfbookmark{Subsection text}{anchor} % below current level
Link Appearance
% Colored text links (preferred for screen)
\hypersetup{colorlinks=true, allcolors=blue}
% Boxed links (default)
\hypersetup{colorlinks=false, pdfborder={0 0 1}}
% Hidden links (for print)
\hypersetup{hidelinks}
% Custom: colored + no underline
\hypersetup{
colorlinks=true,
linkcolor={blue!80!black},
citecolor={green!60!black},
urlcolor={red!70!black},
}
Common Patterns
Clickable TOC with Print-Friendly Style
\usepackage[
colorlinks=true,
linkcolor=black, % TOC/internal links in black
citecolor=blue!50!black,
urlcolor=blue!70!black,
bookmarks=true,
bookmarksnumbered=true,
]{hyperref}
Thesis/Dissertation Setup
\usepackage[
hidelinks, % clean for printing
bookmarks=true,
bookmarksnumbered=true,
bookmarksopen=true,
bookmarksopenlevel=2,
pdftitle={PhD Thesis},
pdfauthor={Name},
]{hyperref}
\usepackage{cleveref}
Back-References in Bibliography
\usepackage[backref=page]{hyperref}
% Adds "Cited on page(s) X, Y" to bibliography entries
Common Pitfalls
| Problem | Cause | Fix |
|---|
| Broken cross-references | hyperref loaded too early | Load hyperref last (before cleveref) |
\autoref says "section" lowercase | Default names | \renewcommand{\sectionautorefname}{Section} |
| Bookmark errors with math | Math in section titles | \texorpdfstring{$E=mc^2$}{E=mc2} |
| "Token not allowed" | Special chars in PDF strings | Use \texorpdfstring{LaTeX}{LaTeX} |
| Links in headers/footers | Fragile commands | Use \protect or \texorpdfstring |
| cleveref not working | Loaded before hyperref | Load order: hyperref → cleveref |
| Link boxes overlap text | Default border style | Use colorlinks=true or hidelinks |
\url breaks wrong | Long URLs | hyperref handles this; check breaklinks=true |
| Conflicts with other packages | Package redefines same commands | Load hyperref after most packages |
Load Order Guide
% Safe order (most common packages):
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{...} % other packages
\usepackage[options]{hyperref} % near last
\usepackage{cleveref} % very last
Tips
- Always use
colorlinks for screen PDFs; hidelinks for print
\texorpdfstring{LaTeX version}{plain text} for anything fancy in section titles\phantomsection before \addcontentsline for correct hyperlinks in unnumbered sections\hypersetup{} can be called multiple times to change settings mid-document- Use
\nohyperpage in index entries to prevent hyperref page linking