Skip to main content

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​

ParameterTypeDefault valueDescription
pageInternalPageModelundefinedThe internal page model to write into.
embeddedFontsReadonlyMap<string, ParsedTrueTypeFont>undefinedThe embedded font registry used for text layout.
fontFamiliesReadonlyMap<string, FontFamilyFaces>...Font families registered with the document, used to resolve a family name plus bold/italic flags to a concrete face.
textDefaults?TextDefaultsundefined-
origin?"bottom-left" | "top-left""bottom-left"-
shapeDefaults?ShapeStyleundefined-

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​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsBmpImageOptionsOptions that control the operation.

Returns​

this


checkBox()​

checkBox(name, options): this;

Adds a checkbox form field to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsCheckBoxOptionsOptions that control the operation.

Returns​

this


choiceField()​

choiceField(name, options): this;

Adds a choice form field to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsChoiceFieldOptionsOptions that control the operation.

Returns​

this


circle()​

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

Draws a circle centered at (cx, cy).

Parameters​

ParameterTypeDescription
cxnumberCenter x in PDF points.
cynumberCenter y in PDF points.
radiusnumberRadius in PDF points.
style?ShapeStyleFill/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​
ParameterTypeDescription
tagPdfContainerTagThe structure tag to create.
build?(container) => voidAn 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​
ParameterTypeDescription
tagPdfContainerTagThe structure tag to create.
options?PdfStructureOptionsOptions that control the operation.
build?(container) => voidAn 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​

ParameterTypeDescription
cxnumberCenter x in PDF points.
cynumberCenter y in PDF points.
rxnumberHorizontal radius in PDF points.
rynumberVertical radius in PDF points.
style?ShapeStyleFill/stroke styling. Stroked when omitted.

Returns​

this


flow()​

flow(options?): PdfFlow;

Creates a cursor-based flow helper for the page.

Parameters​

ParameterTypeDescription
optionsFlowOptionsOptions that control the operation.

Returns​

PdfFlow

The created flow helper.


freeText()​

freeText(options): this;

Adds a free-text annotation to the page.

Parameters​

ParameterTypeDescription
optionsFreeTextAnnotationOptionsOptions that control the operation.

Returns​

this


gif()​

gif(data, options): this;

Adds a GIF image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsGifImageOptionsOptions that control the operation.

Returns​

this


highlight()​

highlight(options): this;

Adds a highlight annotation to the page.

Parameters​

ParameterTypeDescription
optionsHighlightAnnotationOptionsOptions 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​

ParameterTypeDescription
dataBinaryDataThe image bytes.
optionsJpegImageOptionsPlacement and tagging options.

Returns​

this


jbig2()​

jbig2(data, options): this;

Adds a JBIG2 image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsJbig2ImageOptionsOptions that control the operation.

Returns​

this


jp2()​

jp2(data, options): this;

Adds a JPEG 2000 image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsJp2ImageOptionsOptions that control the operation.

Returns​

this


jpeg()​

jpeg(data, options): this;

Adds a JPEG image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsJpegImageOptionsOptions that control the operation.

Returns​

this


line()​

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

Draws a straight line between two points.

Parameters​

ParameterTypeDescription
x1numberStart x in PDF points.
y1numberStart y in PDF points.
x2numberEnd x in PDF points.
y2numberEnd y in PDF points.
style?ShapeStyleStroke styling.

Returns​

this


link(url, options): this;

Adds a URI link annotation to the page.

Parameters​

ParameterTypeDescription
urlstringThe URI target.
optionsUriLinkOptionsOptions that control the operation.

Returns​

this


linkToPage()​

linkToPage(target, options): this;

Adds an internal page link annotation.

Parameters​

ParameterTypeDescription
targetPdfPageThe destination page, outline target, or structure element.
optionsPageLinkOptionsOptions that control the operation.

Returns​

this


list()​

list(items, options): this;

Adds a tagged list to the page.

Parameters​

ParameterTypeDescription
itemsreadonly ListItem[]The list items to add.
optionsListOptionsOptions that control the operation.

Returns​

this


note()​

note(options): this;

Adds a text note annotation to the page.

Parameters​

ParameterTypeDescription
optionsNoteAnnotationOptionsOptions that control the operation.

Returns​

this


path()​

path(commands, style): this;

Adds vector path commands to the page.

Parameters​

ParameterTypeDescription
commandsPathCommand[]The vector path commands to add.
stylePathStyleThe 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​

ParameterTypeDescription
textstringThe text to draw.
optionsTextOptionsText 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​

ParameterTypeDescription
textstringThe text to wrap and draw.
optionsTextBlockOptionsText block options.

Returns​

PlacedTextBlockResult

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


png()​

png(data, options): this;

Adds a PNG image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsPngImageOptionsOptions that control the operation.

Returns​

this


pushButton()​

pushButton(name, options): this;

Adds a push-button form field to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsPushButtonOptionsOptions that control the operation.

Returns​

this


radioGroup()​

radioGroup(name, options): this;

Adds a radio-button group to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsRadioGroupOptionsOptions that control the operation.

Returns​

this


rect()​

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

Draws a rectangle. Convenience wrapper over path.

Parameters​

ParameterTypeDescription
xnumberLeft edge in PDF points.
ynumberBottom edge in PDF points.
widthnumberWidth in PDF points.
heightnumberHeight in PDF points.
style?ShapeStyleFill/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​

ParameterTypeDescription
runsreadonly InlineTextRun[]The styled inline runs to lay out together.
optionsRichTextOptionsBlock 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​

ParameterTypeDescription
degreesnumberThe 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​

ParameterTypeDefault valueDescription
xnumberundefinedThe horizontal transform value.
ynumberxThe 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​

ParameterTypeDescription
optionsExtGStateOptionsAlpha and blend-mode options.

Returns​

this


signatureField()​

signatureField(name, options): this;

Adds a signature form field placeholder to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsSignatureFieldOptionsOptions that control the operation.

Returns​

this


squiggly()​

squiggly(options): this;

Adds a squiggly text-markup annotation to the page.

Parameters​

ParameterTypeDescription
optionsSquigglyAnnotationOptionsOptions that control the operation.

Returns​

this


strikeOut()​

strikeOut(options): this;

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

Parameters​

ParameterTypeDescription
optionsStrikeOutAnnotationOptionsOptions 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​
ParameterTypeDescription
role| string & object | PdfStandardStructureTagThe replacement structure role.
build?(container) => voidAn 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​
ParameterTypeDescription
role| string & object | PdfStandardStructureTagThe replacement structure role.
options?PdfStructureOptionsOptions that control the operation.
build?(container) => voidAn 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​

ParameterTypeDescription
datastring | BinaryDataThe SVG text data.
optionsSvgImageOptionsOptions that control the operation.

Returns​

this


table()​

table(rows, options): this;

Adds a tagged table to the page.

Parameters​

ParameterTypeDescription
rowsreadonly TableRow[]The table rows to add.
optionsTableOptionsOptions that control the operation.

Returns​

this


text()​

text(text, options): this;

Adds text to the page.

Parameters​

ParameterTypeDescription
textstringThe text to add.
optionsTextOptionsOptions that control the operation.

Returns​

this


textBlock()​

textBlock(text, options): this;

Adds a multiline text block to the page.

Parameters​

ParameterTypeDescription
textstringThe text to add.
optionsTextBlockOptionsOptions that control the operation.

Returns​

this


textField()​

textField(name, options): this;

Adds a text form field to the page.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
optionsTextFieldOptionsOptions that control the operation.

Returns​

this


tiff()​

tiff(data, options): this;

Adds a TIFF image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsTiffImageOptionsOptions 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​

ParameterTypeDescription
matrixTransformThe transformation matrix to apply.

Returns​

this


translate()​

translate(x, y): this;

Adds a translation transform to subsequent page operations.

Parameters​

ParameterTypeDescription
xnumberThe horizontal transform value.
ynumberThe vertical transform value.

Returns​

this


underline()​

underline(options): this;

Adds an underline text-markup annotation to the page.

Parameters​

ParameterTypeDescription
optionsUnderlineAnnotationOptionsOptions that control the operation.

Returns​

this


webp()​

webp(data, options): this;

Adds a WebP image to the page.

Parameters​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsWebpImageOptionsOptions that control the operation.

Returns​

this