Add hyperlinks to a PDF — making any region clickable and why this needs low-level annotation surgery
Adding a clickable link to a PDF sounds like it should be a one-click operation, and at the UI level it is — drag a rectangle, paste a URL, done. Underneath, though, this is one of the more technically delicate operations a PDF tool can perform, because hyperlinks in PDF are not part of the page content — they are sibling annotation objects that the viewer overlays for interactivity. Here is what the tool does at the structural level, the four URL schemes supported, and the patterns that distinguish a well-placed hyperlink from one that frustrates readers.
Why this is structurally trickier than it looks
Most PDF modifications happen at the page-content-stream level — drawing text, vectors, images on a page. Hyperlinks are different: they live in the page's /Annots array as separate /Annot objects, not inside the content stream. Each annotation carries its own /Rect (position), /Subtype (Link, in this case), /Border (visual border around the clickable area, usually [0 0 0] for no border), and /A action subtree (what to do when clicked — typically launch a URL).
Pdf-lib has high-level helpers for drawing things into a content stream but no addLink() helper for annotations. The tool constructs the /Annot dictionary manually with the right /Subtype, /Rect (in page coordinates, converted from canvas pixels), /Border, and /A action dictionary, then registers it as a new indirect object and appends its reference to the page's /Annots array. Doable, but not one-liner doable.
Four URL schemes supported
Each scheme behaves slightly differently in PDF readers:
- https:// and http://. Standard web links. Click in any modern PDF reader opens the user's default browser. By far the most common use case.
- mailto:. Email links. Click opens the user's default mail client with the address pre-filled. Useful for contact pages, support links, signup forms.
- tel:. Phone-number links. Click on mobile readers initiates a phone call. Desktop readers may not do anything; mobile readers (iPad Acrobat, Android Adobe, etc.) treat it as a tap-to-dial link.
- file://. Local file references. Click attempts to open a file at the specified path on the reader's machine. Almost never the right choice — paths don't transfer across machines, and security-conscious readers block file:// links by default. Listed for completeness; avoid in shared documents.
Patterns that distinguish good link placement
Five habits that produce well-clickable PDFs:
- Make the click target slightly larger than the visible text. Visible link text might be 10pt and tight. The click rectangle should extend a few points beyond the text on every side so readers don't have to land precisely. The default region you drag is typically larger than the text anyway, which is correct.
- Verify the URL before clicking Apply. Typos in URLs aren't caught at apply time — the link just goes to the typo'd address. Always paste rather than type, and test on the rendered output before sharing.
- Use Highlight PDF to make link regions visible. Hyperlinks have no visible border by default ( /Border [0 0 0]). Readers don't know they're clickable unless the underlying text is styled distinctively. If the link region isn't already styled like a link, run Highlight PDF first with a subtle yellow over the same region.
- Group related links by page. Add all the links on page 1 before moving to page 2. The page navigator preserves your in-progress work, but it's easier to verify completeness when you work page-by-page rather than jumping around.
- Test in multiple readers. Adobe Acrobat, Preview, Chrome, Firefox all handle link clicks slightly differently. Test in at least two before distributing.
Things that don't work in v1
Limitations worth knowing:
- Internal goto-page links. PDF supports internal navigation (clicking a TOC entry jumps to the destination page within the same PDF). That's a different annotation kind (/Action /GoTo rather than /Action /URI). The current tool only handles external URL links. Bookmarks Editor handles internal navigation; it's a paid roadmap item.
- Link borders. All links are placed with /Border [0 0 0] — no visible border. If you want a visible blue underline (web-style hyperlink), apply highlight or text styling separately.
- Link removal. Add Links is additive — it adds new annotations but doesn't modify existing ones. To remove all hyperlinks from a PDF, use Strip Hyperlinks (the inverse tool); both agree on the /Link annotation shape.
Limits and compatibility
On the free web tool, Add Links handles PDFs up to 50 MB. Processing runs in your browser via pdf-lib; nothing is uploaded. Output preserves all existing annotations (additive, not replace) and adds new /Link annotations for every region you defined.
Common pairings: Add Links + Highlight PDF to make link regions visually obvious. Add Links → Flatten to lock the links and content together. Strip Hyperlinks as the inverse if you change your mind.