PDF Association logo

Discover pdfa.org

Key resources

Get involved

How do you find the right PDF technology vendor?
Use the Solution Agent to ask the entire PDF communuity!
The PDF Association celebrates its members’ public statements
of support
for ISO-standardized PDF technology.

Member Area

Screen-shot of long Table of Contents entries line wrapping with Link annotation QuadPoints boundaries highlighted.

Introducing non-rectangular links to PDF

Non-rectangular links are coming to PDF 2.0! This article offers some background to link technology in PDF and discusses the forthcoming Extension to PDF 2.0.
About the author: Peter Wyatt is the PDF Association’s CTO and an independent technology consultant with deep file format and parsing expertise. A developer and researcher working on PDF technologies for more than … Read more
Peter Wyatt

Peter Wyatt
April 7, 2022


Print Friendly, PDF & Email

PDF’s Link annotations enable PDF to support various forms of hyperlinking. Link annotations do not themselves contain any visible content; their purpose is to define the location and shape of a ‘hot area’ on a PDF page, and the actions to occur when a user clicks within the hot area.

Actions triggered by Link annotations can include hyperlinking to a location within the same PDF document, a location in another PDF document, an external URL, or invoking JavaScript or other PDF actions. Link annotations also allow document authors to define various appearance properties of the hot area such as border and highlight styles used by PDF viewers as visual indicators of interactive areas.

Since PDF 1.0 the hot area of a Link annotation was limited to a single rectangle defined by the annotation’s Rect entry. In 2004 PDF 1.6 introduced QuadPoints to facilitate links with multiple quadrilateral areas. This extension enabled efficient hyperlinking when line-wrapping, where a single Link annotation object could be used if the underlying text (for example) was broken across one or more lines on the same page, a common occurrence in Table of Contents with long titles, or in justified columnar text:

Screen-shot of long Table of Contents entries line wrapping with Link annotation QuadPoints boundaries highlighted.

Screen-shot of URLs line wrapping in a narrow column of text with Link annotation QuadPoints boundaries highlighted.

Unlike HTML image maps, however, the page graphics underlying Link annotations are not limited to bitmap images but can also be device-independent vector graphics or text, or any combination. This provides a far better on-screen experience when zooming.

The IsMap feature of URI actions

PDF 1.1 (1996) added the “IsMap” feature to the URI action to support mouse tracking and the communication of the (X,Y) mouse position to a web server:

A URI action’s IsMap attribute indicates that when the action is performed, the (x, y) position of the mouse within the parent link annotation (relative to the upper left hand corner of the link rectangle) should be concatenated to the end of the URI, preceded by a question mark.

This feature mirrors the “image map” capability found in HTML and thus allows HTML web pages and their image map behavior to be faithfully captured into PDF files, but relies on a PDF document and matching web page to process incoming clicks. To demonstrate this, a simple PDF test file (uri-ismap-test.pdf) containing a single image with a single Link annotation and URI action with IsMap set true is located in the GitHub safedocs repository. For demonstration purposes, a matching web page is also in GitHub and is served from the PDF Association at https://safedocs.pdfa.org/uri-ismap-test.html.

To test URI action IsMap support in an interactive viewer, open the PDF file and click anywhere on the image. The web page will then load in your browser and, with a little JavaScript, display the same image with a red dot centered on the (X,Y) coordinates of the click, confirming correct behavior. Viewers that do not support IsMap correctly will be indicated with red error text and no red dot.

Image used to test IsMap support in an interactive viewer.
https://safedocs.pdfa.org/uri-ismap-test.html?419,154 illustrates the correct result if the bottom of the chandelier in the image in the PDF is clicked (X=419, Y=154).

Since the feature invokes an external URL, which might be potentially malicious, it is also expected that all interactive viewers will confirm with users before loading the URL into their web browser. 

Non-Rectangular Links

Until now PDF has never had a purely viewer-only equivalent to the HTML concept of image maps that allow specification of arbitrarily shaped hot areas. ISO 24654 Document management – Portable Document Format – Non-Rectangular Links introduces a Path key to PDF 2.0’s Link annotations that defines an arbitrarily complex set of paths composed of lines and Bezier curves with fallback behavior defined as using QuadPoints (if present) or the Rect bounding box. 

The architecture, engineering and construction (AEC) industries originally proposed this feature to the PDF for Engineering ISO working group (ISO TC 171 SC 2 WG 7) as the AEC sector regularly uses non-rectangular symbols in technical documentation. The new PDF 2.0 non-rectangular Link annotations solve this need, enabling a superior, more intuitive user experience for complex documents.

Architecture symbols


The new PDF 2.0 non-rectangular link capability isn’t just for AEC organizations; it’s useful for any irregular-shaped area in any PDF that requires hyperlinking. Examples might include:

  • a PDF with a map of the world could have complex Paths along each country’s border, with each country hyperlinked to different chapters in the same PDF file.
  • the non-rectangular symbols in flowcharts or process diagrams could be hyperlinked to related content in the same or separate PDFs
  • a circular or irregular company logo could be linked to the company’s website with some appropriate visual effect (e.g., a link border in the company’s palette).

If your organization or documents could benefit from adopting ISO/TS 24654 Document management – Portable Document Format – Non-Rectangular Links, be sure to speak with your PDF vendor to confirm their support schedule.  All draft extension specifications are available to members of the PDF Association through our Category A liaison with ISO for review and comment by technical developers. Developers can also discuss these extensions in the appropriate PDF Association technical community.

In upcoming articles, I will highlight some of the exciting new features in other PDF 2.0 extensions currently in their final ISO balloting phase, as well as a short series of technical articles on how to correctly declare, support and distinguish private data from PDF extensions in PDF processors.

2022-05-02 update: In the May 2022 ISO meetings, ISO TC 171 SC 2 WG7 decided to withhold publication of ISO/TS 24654 in order to resolve some last-minute technical concerns discovered during implementation by a vendor. ISO/TS 24654 will be reworked to correct these issues and is expected to be published in 2023.

WordPress Cookie Notice by Real Cookie Banner