Hyperlinks

Version 6.1.0

In this article

• Links inside a PDF file
• Links to other files
• Links to web URLs
• Links to mail URLs
• Open links in a new window

This article describes how web and file links are added to a MigraDoc document and how bookmarks are used.

Links inside a PDF file

To create a functional hyperlink to another position inside a PDF file, you have to add a bookmark (see Fields for more information).

The hyperlink itself can be added to a Paragraph or FormattedText object. To define the text of the hyperlink, a Text object is added to it.

// Add a hyperlink to bookmark1 to the paragraph.
var hyperlink = paragraph.AddHyperlink(bookmark1);
hyperlink.AddText("link");

See full ToBookmarks sample in PDFsharp.Sample repository. Show resulting PDF

Links to other files

A hyperlink can also target another file:

var otherFilename = "ToBookmarks.pdf";
…
// Add a hyperlink to ToBookmarks sample result PDF file to the paragraph.
// A PDF file link shall be opened in the same window by default.
var hyperlink = paragraph.AddHyperlink(otherFilename, HyperlinkType.File);
hyperlink.AddText("link");

See full ToFiles sample in PDFsharp.Sample repository. Show resulting PDF

For a PDF file, you can also specify a bookmark inside it:

// Create a variable with the name of the bookmark.
// Attention: Value must be identical to the variable in ToBookmarks sample.
var bookmark1 = "bookmark1";
…
// Add a hyperlink to bookmark1 in ToBookmarks sample result PDF file to the paragraph.
// A PDF file link shall be opened in the same window by default.
hyperlink = paragraph.AddHyperlink(otherFilename, bookmark1);
hyperlink.AddText("link");

See full ToFiles sample in PDFsharp.Sample repository. Show resulting PDF

Links to web URLs

A hyperlink can also target a web URL:

// Add a hyperlink to a web URL to the paragraph.
var hyperlink = paragraph.AddHyperlink("https://docs.pdfsharp.net", HyperlinkType.Url);
hyperlink.AddText("link");

See full ToWebUrls sample in PDFsharp.Sample repository. Show resulting PDF

You can also use the static CreateWebLink method. Here, the HTTP protocol is added automatically, if neither HTTP nor HTTPS is specified.

// Add a hyperlink to a web URL file to the paragraph.
// Using CreateWebLink, the HTTP protocol is used, if none is set.
hyperlink = Hyperlink.CreateWebLink("docs.pdfsharp.net");
paragraph.Add(hyperlink);
hyperlink.AddText("link");

See full ToWebUrls sample in PDFsharp.Sample repository. Show resulting PDF

Links to mail URLs

A hyperlink can also open your mail client to write to a given address:

// Add a hyperlink to a mail URL to the paragraph.
var hyperlink = paragraph.AddHyperlink("mailto:john.doe@example.com", HyperlinkType.Url);
hyperlink.AddText("link");

See full ToMailUrls sample in PDFsharp.Sample repository. Show resulting PDF

You can also use the static CreateMailLink method. Here, the mailto protocol is added automatically, if missing.

// Add a hyperlink to a mail URL to the paragraph.
// Using CreateWebLink, the mailto protocol is used, if none is set.
hyperlink = Hyperlink.CreateMailLink("john.doe@example.com");
paragraph.Add(hyperlink);
hyperlink.AddText("link");

See full ToMailUrls sample in PDFsharp.Sample repository. Show resulting PDF

Open links in a new window

A target PDF file is usually opened in the same window or tab. To open it in a new one, use the AddHyperlink overload with the filename, bookmarkName and newWindow parameters and set newWindow to HyperlinkTargetWindow.NewWindow:

// Add a hyperlink to bookmark1 in ToBookmarks sample result PDF file to the paragraph.
// Open this PDF file link in a new window.
hyperlink = paragraph.AddHyperlink(otherFilename, bookmark1, HyperlinkTargetWindow.NewWindow);
hyperlink.AddText("link");

See full NewWindow sample in PDFsharp.Sample repository. Show resulting PDF

Currently you have to use this overload, even if you don’t want to jump to a bookmark. In this case, pass an empty string for the bookmarkName parameter:

// Add a hyperlink to ToBookmarks sample result PDF file to the paragraph.
// Open this PDF file link in a new window.
var hyperlink = paragraph.AddHyperlink(otherFilename, "", HyperlinkTargetWindow.NewWindow);
hyperlink.AddText("link");

See full NewWindow sample in PDFsharp.Sample repository. Show resulting PDF

There is no way to hinder a browser PDF plugin from opening a web link in the same tab by default. The PDF reference specifies the NewWindow entry for remote go-to actions, embedded go-to, and launch actions, but not for URI actions.