LaTeX Hyperlinks: hyperref, \url, \href and Clickable Links

Hyperlinks in LaTeX come from one package: hyperref. Load it and every \ref, \cite and table-of-contents entry becomes clickable, and you get \url and \href for links to the web. This guide covers loading the package correctly, the three URL commands, internal links, the colored boxes everyone wants to remove, PDF metadata, email links, and the errors hyperref is famous for.

Loading hyperref (Last)

hyperref redefines commands from many other packages, so it has to see them first. The rule of thumb: load hyperref as the last package in the preamble. Options can go in the square brackets or in a \hypersetup call, which is easier to read:

\documentclass{article}
\usepackage{graphicx}
\usepackage{amsmath}
\usepackage{booktabs}
% ... all other packages ...
\usepackage{hyperref}
\hypersetup{
  colorlinks=true,
  linkcolor=blue,
  citecolor=blue,
  urlcolor=blue,
}

There are a few well-known exceptions that must be loaded after hyperref because they build on it: cleveref, glossaries, bookmark, hypcap and algorithm (from the algorithms bundle). When in doubt, check the package documentation; most packages that need a special position say so on the first page.

\url, \href and \nolinkurl

The three commands for external links differ in what they print and whether it is clickable:

% Print the address and link it
\url{https://www.useoctree.com/learn}

% Link arbitrary text to an address
\href{https://www.useoctree.com/learn}{the Octree learning hub}

% Print the address in URL style, but do not make it a link
\nolinkurl{https://www.useoctree.com/learn}

• \url{...} typesets the address verbatim in a monospaced font and links it. Special characters such as %, #, ~, & and _ can be typed directly.
• \href{URL}{text} shows text and links to URL. The text is ordinary LaTeX, so it can contain formatting, math or an image.
• \nolinkurl{...} is \url without the link, useful for printed documents or for showing an address inside \href: \href{https://example.org}{\nolinkurl{example.org}}.

Without hyperref, the url package alone provides \url (no link, just correct typesetting). hyperref loads url for you.

Links to local files and relative addresses

\href is not limited to the web. A file: address opens another document, and run: asks the viewer to launch a file with its default application. Whether these work depends on the PDF viewer and its security settings, so use them only for documents that stay on one machine or intranet:

\href{file:./appendix.pdf}{the appendix}
\href{run:./analysis.xlsx}{the spreadsheet}

% A target without a scheme is treated as a local file, not a web URL
\href{appendix.pdf}{the appendix}   % same as file:appendix.pdf

Links to figures or data hosted online are more robust than file links; if a document is going to be emailed or uploaded, prefer a full https:// address.

Line-Breaking Long URLs

By default a URL may break after /, . and a handful of other characters, but not after hyphens and not inside long alphanumeric runs, which leads to overfull lines. Three fixes, from lightest to heaviest:

% 1. Allow breaks at hyphens: pass the option to url BEFORE hyperref
\usepackage[hyphens]{url}
\usepackage{hyperref}

% 2. Add extra break points yourself (after loading hyperref)
\makeatletter
\g@addto@macro{\UrlBreaks}{\UrlOrds}   % also allow breaks after - * ~ ' "
\makeatother

% 3. Let URLs break anywhere: load xurl after hyperref
\usepackage{hyperref}
\usepackage{xurl}

xurl is the simplest modern answer and works with pdfLaTeX, XeLaTeX and LuaLaTeX. The older breakurl package is only needed for the latex → dvips → ps2pdf route, where links otherwise cannot span a line break; do not load it with pdfLaTeX.

URL font

\url uses a typewriter font. Change it for the whole document with \urlstyle:

\urlstyle{same}  % same font as the surrounding text
\urlstyle{tt}    % typewriter (default)
\urlstyle{rm}    % roman
\urlstyle{sf}    % sans-serif

Internal Links: \ref, \autoref, \nameref and \hyperref

With hyperref loaded, every \ref and \pageref becomes a link to the corresponding \label. hyperref adds three more commands, and cleveref adds \cref:

\section{Method}\label{sec:method}

See Section~\ref{sec:method}.            % "Section 2" - only the number is a link
See \autoref{sec:method}.               % "section 2" - name + number, all linked
See \nameref{sec:method}.               % "Method" - the section title, linked
See \hyperref[sec:method]{the method}.  % your own link text

% With cleveref (load after hyperref):
\usepackage{cleveref}
See \cref{sec:method}.                  % "section 2"
See \Cref{sec:method}.                  % "Section 2"

\autoref takes its words from macros such as \sectionautorefname and \figureautorefname. The default for sections is lowercase; to get “Section 2” add \renewcommand{\sectionautorefname}{Section} after loading hyperref. cleveref is more flexible (ranges, lists, capitalisation) and is the better choice for a new document.

Anchors for unnumbered sections: \phantomsection

\section* creates no anchor, so a link to it jumps to the previous one. Insert \phantomsection right before the \addcontentsline:

\clearpage
\phantomsection
\addcontentsline{toc}{section}{Acknowledgements}
\section*{Acknowledgements}\label{sec:ack}

Arbitrary targets: \hypertarget and \hyperlink

To link to a spot that has no counter at all, place a named target and link to it by name:

\hypertarget{data-note}{The raw data were collected in 2025.}
...
As noted \hyperlink{data-note}{earlier}, the data are recent.

Links in the table of contents

In the table of contents only the section title is linked by default. Make the page number clickable too with linktoc=all, or only the page number with linktoc=page:

\hypersetup{linktoc=all}

Removing the Colored Boxes (or Coloring the Links)

Out of the box hyperref draws a colored rectangle around every link: red for internal links, green for citations, cyan for URLs. The boxes are PDF annotations – they show up in viewers but are never printed. Still, most people want them gone. Pick one of the following:

% Option A: no boxes, no colors - links are invisible but still clickable
\usepackage[hidelinks]{hyperref}

% Option B: colored link text instead of boxes (this color DOES print)
\usepackage{hyperref}
\hypersetup{
  colorlinks=true,
  linkcolor=blue,       % internal links: \ref, ToC, footnotes
  citecolor=teal,       % \cite
  urlcolor=magenta,     % \url and \href
  filecolor=magenta,    % links to local files
}

% Option C: keep boxes but make them invisible
\hypersetup{pdfborder={0 0 0}}

% Option D: colored text that still prints black
\hypersetup{colorlinks=true, allcolors=black}

A fourth style, common in theses, is an underline instead of a box or a color: \hypersetup{pdfborderstyle={/S/U/W 1}} draws a one-point line under each link. Like the boxes, it is an annotation and does not print.

allcolors sets every link type at once. For a document that will be printed, the usual choice is colorlinks=true with dark, readable colors, or hidelinks if the links should not be visible on paper at all. Colors can be any xcolor name or definition, e.g. \definecolor{linkblue}{RGB}{0,51,153}.

PDF Metadata and Bookmarks with \hypersetup

hyperref also writes the PDF's document properties and the bookmark panel. Set them once in the preamble:

\hypersetup{
  pdftitle={Fast Hyperlinks in LaTeX},
  pdfauthor={Ada Lovelace},
  pdfsubject={A guide to the hyperref package},
  pdfkeywords={LaTeX, hyperref, PDF},
  pdfpagemode=UseOutlines,   % open with the bookmark panel visible
  bookmarks=true,
  bookmarksopen=true,        % expand the bookmark tree
  bookmarksnumbered=true,    % show section numbers in bookmarks
  unicode=true,              % allow non-ASCII characters in metadata
}

If you would rather reuse \title and \author, load hyperref with the pdfusetitle option. Other useful values for pdfpagemode are UseNone, UseThumbs and FullScreen. The bookmark tree is built from the .out file, so it needs two compilation runs to be complete.

Email Links

An email address is just a URL with the mailto: scheme. Use \href for the link and, if you want the address in the URL font, \nolinkurl for the visible text:

\href{mailto:ada@example.edu}{ada@example.edu}
\href{mailto:ada@example.edu}{\nolinkurl{ada@example.edu}}
\href{mailto:ada@example.edu?subject=Question%20about%20the%20paper}{Email the author}

Links in Section Titles, Captions and Footnotes

Section titles and captions are written to the table of contents and to PDF bookmarks. Bookmarks are plain strings: no math, no formatting, no links. hyperref warns “Token not allowed in a PDF string” and drops the offending tokens. \texorpdfstring gives two versions, one for TeX and one for the bookmark:

\section{Results for \texorpdfstring{$\alpha > 1$}{alpha > 1}}
\section{The \texorpdfstring{\href{https://ctan.org}{CTAN}}{CTAN} archive}

% In a caption, URLs with special characters can break: use a short caption
\caption[Data source]{Data from \protect\url{https://example.org/data}}

% Inside a footnote \url and \href work when the address has no special
% characters (for % # ~ & _ see the next section)
Details are online.\footnote{\url{https://example.org/details}}

Special Characters in URLs

Typed directly in the body of the document, \url and the first argument of \href both accept %, #, ~, & and _ as they are. The exception is when the command sits inside the argument of another command (a \footnote, a \newcommand definition, a \multicolumn or tabularx cell). There the characters are read by TeX before \url sees them. For \href the fix is simple: hyperref accepts the escaped forms \%, \#, \&, \_ and \~ in the URL argument. For \url in such a place, define the address once with \urldef and use the resulting command:

% Fine in running text:
\url{https://example.org/~ada/report_v2.pdf#page=3}
\href{https://example.org/search?q=latex&lang=en}{search}

% Inside another command's argument, escape in \href:
\newcommand{\homepage}{\href{https://example.org/\~ada/a\_b.html\#top}{home}}
Data at 100\% quality.\footnote{\href{https://example.org/?x=1\&y=2}{source}}

% For \url, pre-define the address with \urldef (in the preamble or body)
\urldef{\datalink}\url{https://example.org/~ada/report_v2.pdf#page=3}
\footnote{See \datalink.}

hyperref with Beamer

Beamer loads hyperref itself. Loading it again with options causes an option clash; instead, pass options through the class or with \hypersetup:

\documentclass[hyperref={colorlinks=true, urlcolor=blue}]{beamer}
% or, in the preamble:
\hypersetup{colorlinks=true, urlcolor=blue}

The same applies to other classes and packages that load hyperref for you. A general escape hatch is \PassOptionsToPackage{hidelinks}{hyperref} placed before \documentclass.

Common Errors and Warnings

Complete Example

\documentclass{article}
\usepackage[hyphens]{url}
\usepackage{xcolor}
\usepackage{hyperref}
\usepackage{cleveref}

\hypersetup{
  colorlinks=true,
  linkcolor=blue!60!black,
  citecolor=green!50!black,
  urlcolor=magenta!70!black,
  linktoc=all,
  pdftitle={Hyperlinks in LaTeX},
  pdfauthor={Ada Lovelace},
  pdfkeywords={LaTeX, hyperref},
  bookmarksnumbered=true,
}
\renewcommand{\sectionautorefname}{Section}
\urlstyle{same}

\title{Hyperlinks in LaTeX}
\author{Ada Lovelace\\ \href{mailto:ada@example.edu}{\nolinkurl{ada@example.edu}}}

\begin{document}
\maketitle
\tableofcontents

\section{Introduction}\label{sec:intro}
The \texttt{hyperref} manual lives on
\href{https://ctan.org/pkg/hyperref}{CTAN}; the plain address is
\url{https://ctan.org/pkg/hyperref}. Results follow in \cref{sec:results}.

\section{Results}\label{sec:results}
As promised in \autoref{sec:intro}, see \nameref{sec:intro} and
\hyperref[sec:intro]{the opening section}.

\clearpage
\phantomsection
\addcontentsline{toc}{section}{Acknowledgements}
\section*{Acknowledgements}
Thanks to everyone who reads the manual before asking.
\end{document}

Quick Reference

Next Steps

Links done? Keep polishing the document:

• LaTeX Footnotes – Footnotes in tables, headings and captions, including the hyperfootnotes option
• LaTeX Comments – Single-line, multi-line and block comments, plus todo notes
• Using Colors in LaTeX – Define the xcolor names you use for linkcolor and urlcolor
• Page Size & Margins – Page layout with the geometry package
• Learn LaTeX – Complete beginner tutorial covering all the basics

Free LaTeX Tools

• LaTeX Preview – Test hyperref settings with a live PDF preview
• Citation Generator – Generate BibTeX entries with URLs and DOIs
• LaTeX Symbols Reference – Browse math operators and special characters