@ironsoftware/ironpdf/src/public/annotation.ts

IronPDF for Node

/**
 * Destination type that controls how a PDF reader displays the target page when a
 * bookmark or internal hyperlink is followed.
 *
 * Mirrors {@code IronPdf.Bookmarks.BookmarkDestinations} on the C# side. The numeric
 * value of each entry is what the engine expects on the wire, so the order must match
 * the C# enum.
 *
 * Corresponds to the PDF 1.7 specification §12.3.2 "Explicit Destinations".
 */
export enum BookmarkDestinations {
	/**
	 * Fit the entire destination page within the window (PDF {@code /Fit}).
	 * No additional coordinates are used.
	 */
	Page = 0,
	/**
	 * Scroll to a specific Y coordinate on the destination page while fitting the
	 * page width to the window (PDF {@code /FitH}).
	 * Uses {@link LinkAnnotation.destinationTop}.
	 */
	PageY = 1,
	/**
	 * Scroll to a specific X coordinate on the destination page while fitting the
	 * page height to the window (PDF {@code /FitV}).
	 * Uses {@link LinkAnnotation.destinationLeft}.
	 */
	PageX = 2,
	/**
	 * Scroll to a specific position and zoom level (PDF {@code /XYZ}).
	 * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationTop},
	 * and {@link LinkAnnotation.destinationZoom}. A {@code destinationZoom} of 0 means
	 * "inherit the current zoom".
	 */
	PageZoom = 3,
	/**
	 * Fit the specified rectangle of the destination page into the window (PDF {@code /FitR}).
	 * Uses {@link LinkAnnotation.destinationLeft}, {@link LinkAnnotation.destinationBottom},
	 * {@link LinkAnnotation.destinationRight}, and {@link LinkAnnotation.destinationTop}.
	 */
	PageRect = 4,
	/**
	 * Fit the bounding box of the destination page into the window (PDF {@code /FitB}).
	 */
	PageBounds = 5,
	/**
	 * Scroll to a Y coordinate while fitting the bounding box width to the window
	 * (PDF {@code /FitBH}). Uses {@link LinkAnnotation.destinationTop}.
	 */
	PageBoundsY = 6,
	/**
	 * Scroll to an X coordinate while fitting the bounding box height to the window
	 * (PDF {@code /FitBV}). Uses {@link LinkAnnotation.destinationLeft}.
	 */
	PageBoundsX = 7,
}
 
/**
 * Defines a clickable link annotation that navigates to a specific page within the same
 * PDF document. Useful for building custom tables of contents, cross-references, and
 * in-document navigation.
 *
 * Mirrors {@code IronPdf.Annotations.LinkAnnotation} on the C# side.
 *
 * @example
 * ```ts
 * // Simple TOC link: from page 0 to page 3
 * await pdf.addLinkAnnotation({
 *     pageIndex: 0,
 *     destinationPageIndex: 3,
 *     x: 72, y: 700,
 *     width: 300, height: 18,
 *     contents: "Chapter 1 - Introduction",
 * });
 *
 * // Scroll-to-position link: jump to y=400 on page 1
 * await pdf.addLinkAnnotation({
 *     pageIndex: 0,
 *     destinationPageIndex: 1,
 *     destinationType: BookmarkDestinations.PageZoom,
 *     destinationTop: 400,
 *     destinationZoom: 100,
 *     x: 72, y: 650,
 *     width: 300, height: 18,
 * });
 * ```
 *
 * <b>Coordinate note:</b> {@code y} sets the <em>bottom</em> edge of the clickable area
 * using PDF coordinates (origin at bottom-left of page).
 */
export interface LinkAnnotation {
	/** Zero-based index of the page where the link is placed. */
	pageIndex: number;
	/** Zero-based index of the page to navigate to when clicked. */
	destinationPageIndex: number;
	/**
	 * Destination type controlling how the target page is displayed.
	 * @default BookmarkDestinations.Page
	 */
	destinationType?: BookmarkDestinations;
	/**
	 * Left coordinate of the destination position, in points.
	 * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageX},
	 * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsX}.
	 */
	destinationLeft?: number;
	/**
	 * Right coordinate of the destination position, in points.
	 * Used by {@link BookmarkDestinations.PageRect}.
	 */
	destinationRight?: number;
	/**
	 * Top coordinate of the destination position, in points.
	 * Used by {@link BookmarkDestinations.PageZoom}, {@link BookmarkDestinations.PageY},
	 * {@link BookmarkDestinations.PageRect}, and {@link BookmarkDestinations.PageBoundsY}.
	 */
	destinationTop?: number;
	/**
	 * Bottom coordinate of the destination position, in points.
	 * Used by {@link BookmarkDestinations.PageRect}.
	 */
	destinationBottom?: number;
	/**
	 * Zoom level (in percent) for the destination. Used by
	 * {@link BookmarkDestinations.PageZoom}. A value of 0 means inherit the current zoom.
	 */
	destinationZoom?: number;
	/**
	 * Horizontal X position from the LEFT edge of the page, in points.
	 */
	x: number;
	/**
	 * Vertical Y position from the BOTTOM edge of the page, in points.
	 * PDF coordinate system places Y=0 at the bottom of the page.
	 */
	y: number;
	/** Width of the clickable link area, in points. */
	width: number;
	/** Height of the clickable link area, in points. */
	height: number;
	/**
	 * Color code for the link border in CSS `#RRGGBB` format.
	 * @default undefined (no explicit color)
	 */
	colorCode?: string;
	/**
	 * Whether the link annotation is hidden from users.
	 * @default false
	 */
	hidden?: boolean;
	/**
	 * Descriptive text content for this link annotation.
	 * @default ""
	 */
	contents?: string;
	/**
	 * Title for this link annotation.
	 * @default ""
	 */
	title?: string;
	/**
	 * Whether the link annotation displays a visible border when clicked.
	 * @default false
	 */
	showBorder?: boolean;
}