Configure Links in PDF Files with DevExpress PDF Document API

Nov 07, 2025
8 minutes to read

A PDF file can contain regular hyperlinks and link annotations. Hyperlinks are hypertext links to a URI or document page. Link annotations can navigate to another location within the same document, open a web page, or trigger an action like opening a file or running a script. Link annotations have more visual parameters: border style, width, and highlight mode.

PDF Document API allows you to create both links and link annotations. The following features are available:

Create a Link to a URI or a PagePDF Graphics API allows you to create links as graphics content. You need a reference to the DevExpress.Pdf.Drawing assembly to access the PdfGraphics class.Create Link AnnotationsPDF Facade API ships with members used to create link annotations.

Use PDF Graphics API to Create Hyperlinks

Use the PdfGraphics.AddLinkToUri or PdfGraphics.AddLinkToPage method to create a link to a URI or document page, respectively. These methods use the world coordinate system. Pass a System.Drawing.RectangleF object to these methods to specify where a link should appear on the page. Define the page area in points (1/72 of an inch).

After you create a link at the specified page area, call one of the following methods to draw graphics content on a page:

PdfGraphics.AddToPageForeground, PdfGraphics.AddToPageBackgroundThese methods allow you to draw content on an existing page.PdfDocumentProcessor.RenderNewPageDraws content on a new page.

Note

Coordinate system transformations (for example, system rotation) are not taken into account when the PdfGraphics.AddLinkToUri or PdfGraphics.AddLinkToPage method is called.

Create a Link to a URI

The following code snippet creates the PdfGraphics.AddLinkToUri method to create a link to a URI.

Program.cs
Program.vb

using System;
using DevExpress.Pdf;
using System.Drawing;
using DevExpress.Drawing;

//...
using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {

    // Create an empty document.
    processor.CreateEmptyDocument("..\\..\\Result.pdf");

    // Create and draw graphics.
    using (PdfGraphics graphics = processor.CreateGraphicsPageSystem()) {
        DrawGraphics(graphics);

        // Create a link to URI specifying link area and URI.
        graphics.AddLinkToUri(new RectangleF(310, 150, 180, 15), new Uri("https://www.devexpress.com"));

        // Render a page with graphics.
        processor.RenderNewPage(PdfPaperSize.Letter, graphics);
    }
}

static void DrawGraphics(PdfGraphics graphics)
{
    // Draw a text line on the page.
    DXFont font = new DXFont("Arial", 10);

    DXSolidBrush blue = new DXSolidBrush(Color.Blue);
    graphics.DrawString("https://www.devexpress.com", font, blue, 310, 150);
}

Imports System
Imports DevExpress.Pdf
Imports System.Drawing
Imports DevExpress.Drawing

'...
Using processor As PdfDocumentProcessor = New PdfDocumentProcessor()
    ' Create an empty document.
    processor.CreateEmptyDocument("..\..\Result.pdf")
    ' Create and draw graphics.
    Using graphics As PdfGraphics = processor.CreateGraphicsPageSystem()
        DrawGraphics(graphics)
        ' Create a link to URI specifying link area and URI.
        graphics.AddLinkToUri(New RectangleF(310, 150, 180, 15), New Uri("https://www.devexpress.com"))
        ' Render a page with graphics.
        processor.RenderNewPage(PdfPaperSize.Letter, graphics)
    End Using
End Using

Shared Sub DrawGraphics(ByVal graphics As PdfGraphics)
    ' Draw a text line on the page.
    Dim font As New DXFont("Arial", 10)

    Dim blue As New DXSolidBrush(Color.Blue)
    graphics.DrawString("https://www.devexpress.com", font, blue, 310, 150)
End Sub

Create a Link to a Page

The following code snippet uses the PdfGraphics.AddLinkToPage method to create a link to a page.

Program.cs
Program.vb

using DevExpress.Pdf;
using DevExpress.Drawing;

//...
using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {

    // Create an empty document.
    processor.CreateEmptyDocument("..\\..\\Result.pdf");

    // Create and draw graphics.
    using (PdfGraphics graphics = processor.CreateGraphicsPageSystem()) {
        DrawGraphics(graphics);

        // Create a link to a page specifying link area, the page number and X, Y destinations.
        graphics.AddLinkToPage(new RectangleF(180, 160, 480, 30), 1, 168, 230);

        // Render a page with graphics.
        processor.RenderNewPage(PdfPaperSize.Letter, graphics);
    }
}

static void DrawGraphics(PdfGraphics graphics) {

    // Draw a text line on the page.
    DXSolidBrush black = new DXSolidBrush(Color.Black);
    DXFont font = new DXFont("Times New Roman", 32, DXFontStyle.Bold);

    graphics.DrawString("PDF Document Processor", font, black, 180, 150);
}

Imports DevExpress.Pdf
Imports DevExpress.Drawing

'...
Using processor As PdfDocumentProcessor = New PdfDocumentProcessor()
    ' Create an empty document.
    processor.CreateEmptyDocument("..\..\Result.pdf")
    ' Create and draw graphics.
    Using graphics As PdfGraphics = processor.CreateGraphicsPageSystem()
        DrawGraphics(graphics)
        ' Create a link to a page specifying link area, the page number and X, Y destinations.
        graphics.AddLinkToPage(New RectangleF(180, 160, 480, 30), 1, 168, 230)
        ' Render a page with graphics.
        processor.RenderNewPage(PdfPaperSize.Letter, graphics)
    End Using
End Using

Shared Sub DrawGraphics(ByVal graphics As PdfGraphics)

    ' Draw a text line on the page.
    Dim black As New DXSolidBrush(Color.Black)
    Dim font As New DXFont("Times New Roman", 32, DXFontStyle.Bold)

    graphics.DrawString("PDF Document Processor", font, black, 180, 150)
End Sub

Remove a Link

The PdfPageFacade.ClearContent method overloads clear document content at the specified page areas. You can pass PdfClearContentOptions to these methods to specify what content type to keep.

Note

The PdfPageFacade.ClearContent method uses the user coordinate system.

The following code sample removes only link annotations from the first document page:

Program.cs
Program.vb

csharp

using DevExpress.Pdf;
//...

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    //...

    // Specify the page area to clear.
    PdfRectangle cropBox = processor.Document.Pages[0].CropBox;

    // Specify clear options.
    PdfClearContentOptions options = new PdfClearContentOptions();

    // Remove annotations at the specified page area.
    options.ClearAnnotations = true;

    // Keep text, graphic, and image content of the specified page area.
    options.ClearText = false;
    options.ClearGraphics = false;
    options.ClearImages = false;

    // Clear the page area.
    processor.DocumentFacade.Pages[0].ClearContent(cropBox, options);
}

Imports DevExpress.Pdf
'...

Using processor As New PdfDocumentProcessor()
    '...

    ' Specify the page area to clear.
    Dim cropBox As PdfRectangle = processor.Document.Pages(0).CropBox

    ' Specify clear options.
    Dim options As New PdfClearContentOptions()

    ' Remove annotations at the specified page area.
    options.ClearAnnotations = True

    ' Keep other content of the specified page area.
    options.ClearText = False
    options.ClearGraphics = False
    options.ClearImages = False

    ' Clear the page area.
    processor.DocumentFacade.Pages(0).ClearContent(cropBox, options)
End Using

Use PDF Facade API to Create Link Annotations

The PdfPageFacade.Annotations property retrieves all page annotation properties. Use the PdfDocumentFacade.Pages property to access the PdfPageFacade class.

Other annotation types are available. For additional information, refer to the following help topic: Annotations in PDF Documents.

Call the PdfPageFacade.AddLinkAnnotation method to create a link annotation.

Create an Annotation Linked to a URI String

The following code snippet creates an annotation linked to a URI string:

View Example

C#
VB.NET

csharp

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    // Load a document
    processor.LoadDocument("..\\..\\Document.pdf");

    // Access the first page properties
    PdfPageFacade page = processor.DocumentFacade.Pages[0];

    // Find the target phrase in the document
    string linkText = "Evaluation";
    PdfTextSearchResults linkSearchResults = processor.FindText(linkText);

    if (linkSearchResults.Status == PdfTextSearchStatus.Found)
    {
        PdfRectangle linkRectangle = linkSearchResults.Rectangles[0].BoundingRectangle;
        string linkUri = "https://community.devexpress.com/blogs/";

        // Add a link annotation to the found text
        PdfLinkAnnotationFacade uriAnnotation = page.AddLinkAnnotation(linkRectangle, linkUri);
        uriAnnotation.Name = "link1";
        uriAnnotation.HighlightMode = PdfAnnotationHighlightingMode.Push;
    }
    processor.SaveDocument("..\\..\\Result.pdf");
}

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page properties
  Dim page As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Find the target phrase in the document
  Dim linkText As String = "Evaluation"
  Dim linkSearchResults As PdfTextSearchResults = processor.FindText(linkText)

  If linkSearchResults.Status = PdfTextSearchStatus.Found Then
    Dim linkRectangle As PdfRectangle = linkSearchResults.Rectangles(0).BoundingRectangle
    Dim linkUri As String = "https://community.devexpress.com/blogs/"

    ' Add a link annotation to the found text
    Dim uriAnnotation As PdfLinkAnnotationFacade = page.AddLinkAnnotation(linkRectangle, linkUri)
    uriAnnotation.Name = "link1"
    uriAnnotation.HighlightMode = PdfAnnotationHighlightingMode.Push
  End If
  processor.SaveDocument("..\..\Result.pdf")
End Using

Create a Link to a Destination

A destination includes the following view parameters:

The displayed document page
View parameters: a view mode or a specific point/region on the page to which to navigate
The magnification (zoom factor)

Call one of the following methods to create a destination:

View Parameters	Methods
Fit the page’s bounding box to the document window both horizontally and vertically.	PdfPageFacade.CreateFitBBoxDestination
Fit the page’s bounding box to the document window horizontally.	PdfPageFacade.CreateFitBBoxHorizontallyDestination
Fit the page’s bounding box to the document window vertically.	PdfPageFacade.CreateFitBBoxVerticallyDestination
Fit the entire page to the document window both horizontally and vertically ( Zoom to Page Level view).	PdfPageFacade.CreateFitDestination
Fit the entire page to the document window horizontally.	PdfPageFacade.CreateFitHorizontallyDestination
Fit the entire page to the document window vertically.	PdfPageFacade.CreateFitVerticallyDestination
Display the specified page area in the document window.	PdfPageFacade.CreateFitRectangleDestination
Position the specified page coordinate at the top left document window corner, and specify the zoom factor.	PdfPageFacade.CreateXYZDestination

The following code snippet creates a link annotation with a destination that displays the third page with the Zoom to Page Level view:

View Example

C#
VB.NET

csharp

using (PdfDocumentProcessor pdfDocumentProcessor = new PdfDocumentProcessor())
{
    // Load a document
    pdfDocumentProcessor.LoadDocument("Demo.pdf");

    // Access third page properties
    PdfPageFacade pageFacade = pdfDocumentProcessor.DocumentFacade.Pages[2];

    // Create a Fit destination that refers to the third page
    PdfFitDestination destination = pageFacade.CreateFitDestination();

    // Find a specific phrase
    string linkText = "JBIG2 images";
    PdfTextSearchResults linkSearchResults = pdfDocumentProcessor.FindText(linkText);

    // If the phrase is found, obtain its bounding rectangle
    if (linkSearchResults.Status == PdfTextSearchStatus.Found)
    {
        PdfRectangle linkRectangle = linkSearchResults.Rectangles[0].BoundingRectangle;

        // Access first page properties
        PdfPageFacade linkPageFacade =
           pdfDocumentProcessor.DocumentFacade.Pages[linkSearchResults.PageNumber -1];

        // Create a link annotation associated with the bounding rectangle
        // and destination
        PdfLinkAnnotationFacade linkAnnotation =
            linkPageFacade.AddLinkAnnotation(linkRectangle, destination);
        linkAnnotation.HighlightMode = PdfAnnotationHighlightingMode.Push;
    }
    // Save the result
    pdfDocumentProcessor.SaveDocument("out.pdf");
}

Using pdfDocumentProcessor As New PdfDocumentProcessor()
  ' Load a document
  pdfDocumentProcessor.LoadDocument("Demo.pdf")

  ' Access third page properties
  Dim pageFacade As PdfPageFacade = pdfDocumentProcessor.DocumentFacade.Pages(2)

  ' Create a Fit destination that refers to the third page
    Dim destination As PdfFitDestination = pageFacade.CreateFitDestination()

  ' Find a specific phrase
  Dim linkText As String = "JBIG2 images"
  Dim linkSearchResults As PdfTextSearchResults = pdfDocumentProcessor.FindText(linkText)

  ' If the phrase is found, obtain its bounding rectangle
  If linkSearchResults.Status = PdfTextSearchStatus.Found Then
    Dim linkRectangle As PdfRectangle = linkSearchResults.Rectangles(0).BoundingRectangle

    ' Access first page properties
    Dim linkPageFacade As PdfPageFacade = pdfDocumentProcessor.DocumentFacade.Pages(linkSearchResults.PageNumber -1)

    'Create a link annotation associated with the bounding rectangle
    ' and destination
    Dim linkAnnotation As PdfLinkAnnotationFacade =
       linkPageFacade.AddLinkAnnotation(linkRectangle, destination)
    linkAnnotation.HighlightMode = PdfAnnotationHighlightingMode.Push
  End If
  ' Save the result
  pdfDocumentProcessor.SaveDocument("out.pdf")
End Using