Add Clickable URL Links

Recipe adds URL actions using top-left coordinates. Use link() when the clickable region is independent of its content, such as a custom drawing:

var outputBytes = new Recipe()
  .createPage(595, 842)
  .rectangle(65, 100, 465, 120, { fill: "#dbeafe" })
  .link("https://example.com", 65, 100, 465, 120)
  .endPage()
  .endPDF();

Text, images, and supported shapes can instead calculate their clickable rectangle from their rendered bounds:

recipe
  .text("Visit our site", 65, 250, {
    color: "#0563c1",
    underline: true,
    link: "https://example.com",
  })
  .image("logo", 65, 290, {
    width: 120,
    link: "https://example.com",
  })
  .rectangle(65, 450, 180, 48, {
    fill: "#dbeafe",
    link: "https://example.com",
  });

With html: true, <a href="https://example.com">Visit our site</a> creates a link over the rendered text. PDF link annotations are rectangular; use link() to select the clickable region for complex drawings.

Use an ASCII URL. Percent-encode non-ASCII path or query text, for example encodeURI("https://example.com/✓"), before passing it to link() or a link option. Unsupported URLs throw when the link is added, so the page can still be finalized.

Link coordinates and dimensions must be finite numbers. A negative width or height extends the link leftward or upward, as it does for the shapes that carry a link option. Recipe checks the resulting PDF rectangle before queuing the link on new and edited pages. Invalid rectangles throw a TypeError from link() and leave the page available for further drawing and finalization.

With textBox.wrap: "clip", text links are limited to the line's clipping region. Hidden overflow does not create clickable areas outside the text box.

The low-level API uses PDF bottom-left rectangle coordinates. Pause an active page content context before attaching the link:

var context = writer.startPageContentContext(page);
context.drawRectangle(88, 694, 112, 26, { color: 0xdbeafe });

writer
  .pausePageContentContext(context)
  .attachURLLinktoCurrentPage("https://example.com", 88, 694, 200, 720)
  .writePage(page);

var outputBytes = writer.end();

The PDF viewer decides how link regions are indicated and whether navigation requires confirmation.