Class: PdfPage

A mutable page builder for placing text, graphics, images, links, annotations, form fields, and structured content on a PDF page.

Constructors

Constructor

new PdfPage(
   page, 
   embeddedFonts, 
   fontFamilies?, 
   textDefaults?, 
   origin?, 
   shapeDefaults?): PdfPage;

Creates a page builder around an internal page model and embedded font registry.

Parameters

Parameter	Type	Default value	Description
`page`	`InternalPageModel`	`undefined`	The internal page model to write into.
`embeddedFonts`	`ReadonlyMap`<`string`, `ParsedTrueTypeFont`>	`undefined`	The embedded font registry used for text layout.
`fontFamilies`	`ReadonlyMap`<`string`, `FontFamilyFaces`>	`...`	Font families registered with the document, used to resolve a family name plus `bold`/`italic` flags to a concrete face.
`textDefaults?`	`TextDefaults`	`undefined`	-
`origin?`	`"bottom-left"` \| `"top-left"`	`"bottom-left"`	-
`shapeDefaults?`	`ShapeStyle`	`undefined`	-

Returns

PdfPage

Accessors

size

Get Signature

get size(): CustomPageSize;

Gets the page size.

Returns

CustomPageSize

The number of bytes.

Methods

bmp()

bmp(data, options): this;

Adds a BMP image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`BmpImageOptions`	Options that control the operation.

Returns

this

checkBox()

checkBox(name, options): this;

Adds a checkbox form field to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`CheckBoxOptions`	Options that control the operation.

Returns

this

choiceField()

choiceField(name, options): this;

Adds a choice form field to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`ChoiceFieldOptions`	Options that control the operation.

Returns

this

circle()

circle(
   cx, 
   cy, 
   radius, 
   style?): this;

Draws a circle centered at (cx, cy).

Parameters

Parameter	Type	Description
`cx`	`number`	Center x in PDF points.
`cy`	`number`	Center y in PDF points.
`radius`	`number`	Radius in PDF points.
`style?`	`ShapeStyle`	Fill/stroke styling. Stroked when omitted.

Returns

this

container()

Creates a tagged structure container on the page.

Param

The structure tag to create.

Param

Either structure options or a build callback.

Param

An optional build callback when options are provided separately.

Call Signature

container(tag, build?): PdfStructureContainer;

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
`tag`	`PdfContainerTag`	The structure tag to create.
`build?`	(`container`) => `void`	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

Call Signature

container(
   tag, 
   options?, 
   build?): PdfStructureContainer;

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
`tag`	`PdfContainerTag`	The structure tag to create.
`options?`	`PdfStructureOptions`	Options that control the operation.
`build?`	(`container`) => `void`	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

ellipse()

ellipse(
   cx, 
   cy, 
   rx, 
   ry, 
   style?): this;

Draws an ellipse centered at (cx, cy) with horizontal radius rx and vertical radius ry.

Parameters

Parameter	Type	Description
`cx`	`number`	Center x in PDF points.
`cy`	`number`	Center y in PDF points.
`rx`	`number`	Horizontal radius in PDF points.
`ry`	`number`	Vertical radius in PDF points.
`style?`	`ShapeStyle`	Fill/stroke styling. Stroked when omitted.

Returns

this

flow()

flow(options?): PdfFlow;

Creates a cursor-based flow helper for the page.

Parameters

Parameter	Type	Description
`options`	`FlowOptions`	Options that control the operation.

Returns

PdfFlow

The created flow helper.

freeText()

freeText(options): this;

Adds a free-text annotation to the page.

Parameters

Parameter	Type	Description
`options`	`FreeTextAnnotationOptions`	Options that control the operation.

Returns

this

gif()

gif(data, options): this;

Adds a GIF image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`GifImageOptions`	Options that control the operation.

Returns

this

highlight()

highlight(options): this;

Adds a highlight annotation to the page.

Parameters

Parameter	Type	Description
`options`	`HighlightAnnotationOptions`	Options that control the operation.

Returns

this

image()

image(data, options): this;

Adds a raster image, auto-detecting the format (PNG, JPEG, GIF, BMP, TIFF, WebP, JPEG 2000) from the data. For SVG use svg.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The image bytes.
`options`	`JpegImageOptions`	Placement and tagging options.

Returns

this

jbig2()

jbig2(data, options): this;

Adds a JBIG2 image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`Jbig2ImageOptions`	Options that control the operation.

Returns

this

jp2()

jp2(data, options): this;

Adds a JPEG 2000 image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`Jp2ImageOptions`	Options that control the operation.

Returns

this

jpeg()

jpeg(data, options): this;

Adds a JPEG image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`JpegImageOptions`	Options that control the operation.

Returns

this

line()

line(
   x1, 
   y1, 
   x2, 
   y2, 
   style?): this;

Draws a straight line between two points.

Parameters

Parameter	Type	Description
`x1`	`number`	Start x in PDF points.
`y1`	`number`	Start y in PDF points.
`x2`	`number`	End x in PDF points.
`y2`	`number`	End y in PDF points.
`style?`	`ShapeStyle`	Stroke styling.

Returns

this

link()

link(url, options): this;

Adds a URI link annotation to the page.

Parameters

Parameter	Type	Description
`url`	`string`	The URI target.
`options`	`UriLinkOptions`	Options that control the operation.

Returns

this

linkToPage()

linkToPage(target, options): this;

Adds an internal page link annotation.

Parameters

Parameter	Type	Description
`target`	`PdfPage`	The destination page, outline target, or structure element.
`options`	`PageLinkOptions`	Options that control the operation.

Returns

this

list()

list(items, options): this;

Adds a tagged list to the page.

Parameters

Parameter	Type	Description
`items`	readonly `ListItem`[]	The list items to add.
`options`	`ListOptions`	Options that control the operation.

Returns

this

note()

note(options): this;

Adds a text note annotation to the page.

Parameters

Parameter	Type	Description
`options`	`NoteAnnotationOptions`	Options that control the operation.

Returns

this

path()

path(commands, style): this;

Adds vector path commands to the page.

Parameters

Parameter	Type	Description
`commands`	`PathCommand`[]	The vector path commands to add.
`style`	`PathStyle`	The drawing style for the path.

Returns

this

placeText()

placeText(text, options): PlacedTextResult;

Draws a single line of text and returns its measured size plus endY — the y where the next element can start. Unlike text (which chains), this returns layout feedback for manual stacking.

Parameters

Parameter	Type	Description
`text`	`string`	The text to draw.
`options`	`TextOptions`	Text options.

Returns

PlacedTextResult

{ width, height, endY } in PDF points.

placeTextBlock()

placeTextBlock(text, options): PlacedTextBlockResult;

Draws a wrapped text block and returns its measured size, line count, and endY — the y just below the block, for stacking the next element.

Parameters

Parameter	Type	Description
`text`	`string`	The text to wrap and draw.
`options`	`TextBlockOptions`	Text block options.

Returns

PlacedTextBlockResult

{ width, height, lineCount, endY } in PDF points.

png()

png(data, options): this;

Adds a PNG image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`PngImageOptions`	Options that control the operation.

Returns

this

pushButton()

pushButton(name, options): this;

Adds a push-button form field to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`PushButtonOptions`	Options that control the operation.

Returns

this

radioGroup()

radioGroup(name, options): this;

Adds a radio-button group to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`RadioGroupOptions`	Options that control the operation.

Returns

this

rect()

rect(
   x, 
   y, 
   width, 
   height, 
   style?): this;

Draws a rectangle. Convenience wrapper over path.

Parameters

Parameter	Type	Description
`x`	`number`	Left edge in PDF points.
`y`	`number`	Bottom edge in PDF points.
`width`	`number`	Width in PDF points.
`height`	`number`	Height in PDF points.
`style?`	`ShapeStyle`	Fill/stroke styling. Stroked when omitted.

Returns

this

restoreState()

restoreState(): this;

Restores the most recently saved graphics state.

Returns

this

richText()

richText(runs, options): this;

Adds a paragraph of inline rich-text runs. Each InlineTextRun carries its own style yet the runs flow on the same line and wrap together as one paragraph. Runs that omit a style inherit it from options, then from the document defaults; runs carrying a link become clickable.

Supports left/center/right/justify alignment via options.align, line-level direction ("ltr"/"rtl"/"auto"), and writingMode: "vertical" (single column). In the flow and template layouts the paragraph wraps and splits across columns and pages.

Parameters

Parameter	Type	Description
`runs`	readonly `InlineTextRun`[]	The styled inline runs to lay out together.
`options`	`RichTextOptions`	Block geometry and inherited style defaults.

Returns

this

Example

page.richText(
  [
    { text: "Read the " },
    { text: "terms", bold: true, link: "https://x.com/terms" },
    { text: " before continuing." },
  ],
  { x: 56, y: 700, width: 300, fontSize: 12 },
);

rotate()

rotate(degrees): this;

Adds a rotation transform to subsequent page operations.

Parameters

Parameter	Type	Description
`degrees`	`number`	The rotation angle in degrees.

Returns

this

saveState()

saveState(): this;

Saves the current graphics state.

Returns

this

scale()

scale(x, y?): this;

Adds a scale transform to subsequent page operations.

Parameters

Parameter	Type	Default value	Description
`x`	`number`	`undefined`	The horizontal transform value.
`y`	`number`	`x`	The vertical transform value.

Returns

this

setExtGState()

setExtGState(options): this;

Sets graphics-state parameters (alpha and/or blend mode) for subsequent painting operations. Emitted as an inline ExtGState entry referenced by the gs operator. Pair with saveState/restoreState to scope the effect.

Parameters

Parameter	Type	Description
`options`	`ExtGStateOptions`	Alpha and blend-mode options.

Returns

this

signatureField()

signatureField(name, options): this;

Adds a signature form field placeholder to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`SignatureFieldOptions`	Options that control the operation.

Returns

this

squiggly()

squiggly(options): this;

Adds a squiggly text-markup annotation to the page.

Parameters

Parameter	Type	Description
`options`	`SquigglyAnnotationOptions`	Options that control the operation.

Returns

this

strikeOut()

strikeOut(options): this;

Adds a strike-out text-markup annotation to the page.

Parameters

Parameter	Type	Description
`options`	`StrikeOutAnnotationOptions`	Options that control the operation.

Returns

this

structure()

Creates a tagged structure container on the page.

Param

The replacement structure role.

Param

Either structure options or a build callback.

Param

An optional build callback when options are provided separately.

Call Signature

structure(role, build?): PdfStructureContainer;

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
`role`	\| `string` & `object` \| `PdfStandardStructureTag`	The replacement structure role.
`build?`	(`container`) => `void`	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

Call Signature

structure(
   role, 
   options?, 
   build?): PdfStructureContainer;

Creates a tagged structure container on the page.

Parameters

Parameter	Type	Description
`role`	\| `string` & `object` \| `PdfStandardStructureTag`	The replacement structure role.
`options?`	`PdfStructureOptions`	Options that control the operation.
`build?`	(`container`) => `void`	An optional callback that receives the created container.

Returns

PdfStructureContainer

The created structure container.

svg()

svg(data, options): this;

Adds an SVG graphic to the page.

Parameters

Parameter	Type	Description
`data`	`string` \| `BinaryData`	The SVG text data.
`options`	`SvgImageOptions`	Options that control the operation.

Returns

this

table()

table(rows, options): this;

Adds a tagged table to the page.

Parameters

Parameter	Type	Description
`rows`	readonly `TableRow`[]	The table rows to add.
`options`	`TableOptions`	Options that control the operation.

Returns

this

text()

text(text, options): this;

Adds text to the page.

Parameters

Parameter	Type	Description
`text`	`string`	The text to add.
`options`	`TextOptions`	Options that control the operation.

Returns

this

textBlock()

textBlock(text, options): this;

Adds a multiline text block to the page.

Parameters

Parameter	Type	Description
`text`	`string`	The text to add.
`options`	`TextBlockOptions`	Options that control the operation.

Returns

this

textField()

textField(name, options): this;

Adds a text form field to the page.

Parameters

Parameter	Type	Description
`name`	`string`	The name to assign or look up.
`options`	`TextFieldOptions`	Options that control the operation.

Returns

this

tiff()

tiff(data, options): this;

Adds a TIFF image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`TiffImageOptions`	Options that control the operation.

Returns

this

toInternalModel()

toInternalModel(): InternalPageModel;

Returns the internal page model used by serializers and editors.

Returns

InternalPageModel

The internal page model.

transform()

transform(matrix): this;

Adds a raw transformation matrix to subsequent page operations.

Parameters

Parameter	Type	Description
`matrix`	`Transform`	The transformation matrix to apply.

Returns

this

translate()

translate(x, y): this;

Adds a translation transform to subsequent page operations.

Parameters

Parameter	Type	Description
`x`	`number`	The horizontal transform value.
`y`	`number`	The vertical transform value.

Returns

this

underline()

underline(options): this;

Adds an underline text-markup annotation to the page.

Parameters

Parameter	Type	Description
`options`	`UnderlineAnnotationOptions`	Options that control the operation.

Returns

this

webp()

webp(data, options): this;

Adds a WebP image to the page.

Parameters

Parameter	Type	Description
`data`	`BinaryData`	The binary image or font data.
`options`	`WebpImageOptions`	Options that control the operation.

Returns

this

Constructors​

Constructor​

Parameters​

Returns​

Accessors​

size​

Get Signature​

Returns​

Methods​

bmp()​

Parameters​

Returns​

checkBox()​

Parameters​

Returns​

choiceField()​

Parameters​

Returns​

circle()​

Parameters​

Returns​

container()​

Param​

Param​

Param​

Call Signature​

Parameters​

Returns​

Call Signature​

Parameters​

Returns​

ellipse()​

Parameters​

Returns​

flow()​

Parameters​

Returns​

freeText()​

Parameters​

Returns​

gif()​

Parameters​

Returns​

highlight()​

Parameters​

Returns​

image()​

Parameters​

Returns​

jbig2()​

Parameters​

Returns​

jp2()​

Parameters​

Returns​

jpeg()​

Parameters​

Returns​

line()​

Parameters​

Returns​

link()​

Parameters​

Returns​

linkToPage()​

Parameters​

Returns​

list()​

Parameters​

Returns​

note()​

Parameters​

Returns​

path()​

Parameters​

Returns​

placeText()​

Parameters​

Returns​

placeTextBlock()​

Constructors

Constructor

Parameters

Returns

Accessors

size

Get Signature

Returns

Methods

bmp()

Parameters

Returns

checkBox()

Parameters

Returns

choiceField()

Parameters

Returns

circle()

Parameters

Returns

container()

Param

Param

Param

Call Signature

Parameters

Returns

Call Signature

Parameters

Returns

ellipse()

Parameters

Returns

flow()

Parameters

Returns

freeText()

Parameters

Returns

gif()

Parameters

Returns

highlight()

Parameters

Returns

image()

Parameters

Returns

jbig2()

Parameters

Returns

jp2()

Parameters

Returns

jpeg()

Parameters

Returns

line()

Parameters

Returns

link()

Parameters

Returns

linkToPage()

Parameters

Returns

list()

Parameters

Returns

note()

Parameters

Returns

path()

Parameters

Returns

placeText()

Parameters

Returns

placeTextBlock()