Document Navigation Annotations

• Jul 21, 2026
• 5 minutes to read

A link annotation defines a clickable region on a PDF page. When a user clicks the region, the annotation navigates to a destination or executes an action.

To add a link annotation to a page, do the following:

1. Create a LinkAnnotation.
2. Assign an action to the link annotation.
3. Add the link annotation to the page’s annotation collection.

Supported Link Actions

To assign an action to a link annotation, create an InteractiveAction descendant and pass it to the setAction(InteractiveAction value) method.

The PDF Document API supports the following link actions:

Action	Description
UriAction	Opens a web page or another URI.
GoToAction	Navigates to a page in the current PDF document.
RemoteGoToAction	Navigates to a page in another PDF document.
JavaScriptAction	Executes JavaScript code.
NamedAction	Executes a predefined PDF viewer command, such as Print, Find, or Next Page.

Create a Link to a Web Page

Assign a UriAction object to the annotation.

The following code snippet creates a link annotation that opens the DevExpress website:

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;

import java.io.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (InputStream documentStream =
                     Files.newInputStream(Path.of("Document.pdf"));
             PdfDocument pdfDocument = new PdfDocument(documentStream)) {

            Page page = pdfDocument.getPages().getFirst();

            // Add link text.
            float textX = 50;
            float textY = 800;
            TextFragment textFragment = new TextFragment() {{
                setText("Visit the DevExpress website");
                setLocation(new PointF(textX, textY));
            }};
            page.getFragments().add(textFragment);

            // Create a link annotation.
            float textWidth = textFragment.measure().getSize().getWidth();
            float textHeight = textFragment.measure().getSize().getHeight();
            float offset = 10;

            LinkAnnotation link = new LinkAnnotation(new RectangleF(
                    textX - offset,
                    textY - offset,
                    textWidth + offset * 2,
                    textHeight + offset * 2));

            UriAction action = new UriAction();
            action.setUri("https://www.devexpress.com");

            link.setAction(action);
            link.setHighlightingMode(AnnotationHighlightingMode.INVERT);

            page.getAnnotations().add(link);

            pdfDocument.save(Files.newOutputStream(Path.of("Result.pdf")));
        }
    }
}

Create a Link to a PDF Page

1. Create a GoToAction object.
2. Create a FitDestination and pass it to the setDestination(Destination value) method.
3. Call the setPage(Page value) method to specify the destination page.
4. Assign the GoToAction object to the annotation.

The following code snippet creates a link annotation that opens the specified page in the current document:

void createGoToActionLinkAnnotation(Page page, Page destinationPage) {
    // Add link text.
    float textX = 50;
    float textY = 700;
    TextFragment textFragment = new TextFragment() {{
        setText("Learn More");
        setLocation(new PointF(textX, textY));
    }};
    page.getFragments().add(textFragment);

    // Create a link annotation.
    float textWidth = textFragment.measure().getSize().getWidth();
    float textHeight = textFragment.measure().getSize().getHeight();
    float offset = 10;

    LinkAnnotation link = new LinkAnnotation(new RectangleF(
            textX - offset,
            textY - offset,
            textWidth + offset * 2,
            textHeight + offset * 2));

    GoToAction action = new GoToAction();
    action.setDestination(new FitDestination());
    action.setPage(destinationPage);

    link.setAction(action);
    link.setHighlightingMode(AnnotationHighlightingMode.PUSH);

    page.getAnnotations().add(link);
}

Create a Link to a PDF Document

Assign a RemoteGoToAction to the annotation.

The following code snippet creates a link annotation that opens another PDF document:

package pdf;

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;

import java.nio.channels.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (FileChannel fileChannel = FileChannel.open(Path.of("Document.pdf"));
             PdfDocument pdfDocument = new PdfDocument(fileChannel)) {

            Page page = pdfDocument.getPages().getFirst();

            createRemoteLinkAnnotation(page, "Invoice.pdf", 0);

            try (WritableByteChannel channel =
                         FileChannel.open(Path.of("Result.pdf"),
                                 StandardOpenOption.CREATE,
                                 StandardOpenOption.WRITE,
                                 StandardOpenOption.TRUNCATE_EXISTING)) {

                pdfDocument.save(channel);
            }
        }
    }

    static void createRemoteLinkAnnotation(Page page, String fileName, int pageIndex) {
        float textX = 50;
        float textY = 700;
        TextFragment textFragment = new TextFragment() {{
            setText("Open Invoice");
            setLocation(new PointF(textX, textY));
        }};
        page.getFragments().add(textFragment);

        float textWidth = textFragment.measure().getSize().getWidth();
        float textHeight = textFragment.measure().getSize().getHeight();
        float offset = 10;

        LinkAnnotation link = new LinkAnnotation(new RectangleF(
                textX - offset,
                textY - offset,
                textWidth + offset * 2,
                textHeight + offset * 2));

        RemoteGoToAction action = new RemoteGoToAction();
        action.setPageIndex(pageIndex);
        action.setFileSpecification(
                new FileSpecification(){{
                    setFileName(fileName);
                }});
        action.setOpenInNewWindow(true);

        link.setAction(action);
        page.getAnnotations().add(link);
    }
}

Attach a Link to Existing Text

Search for text in the document, obtain its bounding region, and assign this region to a link annotation.

The following code snippet creates a link over the text “DevExpress”:

package pdf;

import com.devexpress.docs.pdf.*;
import com.devexpress.system.drawing.*;

import java.nio.channels.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (FileChannel fileChannel = FileChannel.open(Path.of("Document.pdf"));
             PdfDocument pdfDocument = new PdfDocument(fileChannel)) {

            Page page = pdfDocument.getPages().getFirst();

            createTextLinkAnnotation(pdfDocument);

            try (WritableByteChannel channel =
                         FileChannel.open(Path.of("Result.pdf"),
                                 StandardOpenOption.CREATE,
                                 StandardOpenOption.WRITE,
                                 StandardOpenOption.TRUNCATE_EXISTING)) {

                pdfDocument.save(channel);
            }
        }
    }

    static void createTextLinkAnnotation(PdfDocument pdfDocument) {
        TextSearchOptions searchOptions = new TextSearchOptions(true, true);

        var results = pdfDocument.findText("DevExpress", searchOptions);

        for(TextSearchInfo searchResult : results) {
            for (TextMatchInfo match : searchResult.getMatches()) {
                var fragments = match.getMatchFragments();
                var link = new LinkAnnotation(
                        fragments
                                .getFirst()
                                .getRectangle()
                                .getBoundingBox());

                var action = new UriAction();
                action.setUri("https://www.devexpress.com/");
                link.setAction(action);

                pdfDocument.getPages()
                        .get(searchResult.getPageIndex())
                        .getAnnotations()
                        .add(link);
            }
        }
    }
}

Specify the Highlight Mode

Use the LinkAnnotation.setHighlightingMode() method to specify the visual effect displayed when the user clicks the link.

The following highlighting modes are available:

Value	Description
NONE	Displays no visual effect.
INVERT	Inverts annotation colors.
OUTLINE	Inverts the annotation border.
PUSH	Displays the annotation as pressed.

Customize the Link Border

Use the LinkAnnotation.setBorderStyle() method to specify the border appearance.

The following code snippet creates a solid blue border:

// Draw a solid blue border around the link annotation.
AnnotationBorderStyle border = new AnnotationBorderStyle();

border.setWidth(2);
border.setStyle(BorderStyle.SOLID);

// Link annotation creation and initialization are omitted.
// See the previous example for the complete code.
link.setBorderStyle(border);
link.setColor(PdfColor.getBlue());