PDFPage
Represents a single page of a [[PDFDocument]].
Class PDFPage
class PDFPageRepresents a single page of a [[PDFDocument]].
Properties
doc
PDFDocumentThe document to which this page belongs.
node
PDFPageLeafThe low-level PDFDictionary wrapped by this page.
ref
PDFRefThe unique reference assigned to this page within the document.
create
(doc: PDFDocument) => PDFPageNOTE: You probably don't want to call this method directly. Instead, consider using the [[PDFDocument.addPage]] and [[PDFDocument.insertPage]] methods, which can create instances of [[PDFPage]] for you.
Create an instance of [[PDFPage]].
of
(leafNode: PDFPageLeaf, ref: PDFRef, doc: PDFDocument) => PDFPageNOTE: You probably don't want to call this method directly. Instead, consider using the [[PDFDocument.addPage]] and [[PDFDocument.insertPage]] methods, which can create instances of [[PDFPage]] for you.
Create an instance of [[PDFPage]] from an existing leaf node.
Methods
drawCircle
drawCircle(options?: PDFPageDrawCircleOptions): voidDraw a circle on this page. For example:
import { grayscale, rgb } from 'pdf-lib'
page.drawCircle({
x: 200,
y: 150,
size: 100,
borderWidth: 5,
borderColor: grayscale(0.5),
color: rgb(0.75, 0.2, 0.2),
opacity: 0.5,
borderOpacity: 0.75,
})Parameters
options?: PDFPageDrawCircleOptionsThe options to be used when drawing the ellipse.
Returns void
drawEllipse
drawEllipse(options?: PDFPageDrawEllipseOptions): voidDraw an ellipse on this page. For example:
import { grayscale, rgb } from 'pdf-lib'
page.drawEllipse({
x: 200,
y: 75,
xScale: 100,
yScale: 50,
borderWidth: 5,
borderColor: grayscale(0.5),
color: rgb(0.75, 0.2, 0.2),
opacity: 0.5,
borderOpacity: 0.75,
})Parameters
options?: PDFPageDrawEllipseOptionsThe options to be used when drawing the ellipse.
Returns void
drawImage
drawImage(image: PDFImage, options?: PDFPageDrawImageOptions): voidDraw an image on this page. For example:
import { degrees } from 'pdf-lib'
const jpgUrl = 'https://pdf-lib.js.org/assets/cat_riding_unicorn.jpg'
const jpgImageBytes = await fetch(jpgUrl).then((res) => res.arrayBuffer())
const jpgImage = await pdfDoc.embedJpg(jpgImageBytes)
const jpgDims = jpgImage.scale(0.5)
const page = pdfDoc.addPage()
page.drawImage(jpgImage, {
x: 25,
y: 25,
width: jpgDims.width,
height: jpgDims.height,
rotate: degrees(30),
opacity: 0.75,
})Parameters
image: PDFImageThe image to be drawn.options?: PDFPageDrawImageOptionsThe options to be used when drawing the image.
Returns void
drawLine
drawLine(options: PDFPageDrawLineOptions): voidDraw a line on this page. For example:
import { rgb } from 'pdf-lib'
page.drawLine({
start: { x: 25, y: 75 },
end: { x: 125, y: 175 },
thickness: 2,
color: rgb(0.75, 0.2, 0.2),
opacity: 0.75,
})Parameters
options: PDFPageDrawLineOptionsThe options to be used when drawing the line.
Returns void
drawPage
drawPage(embeddedPage: PDFEmbeddedPage, options?: PDFPageDrawPageOptions): voidDraw an embedded PDF page on this page. For example:
import { degrees } from 'pdf-lib'
const pdfDoc = await PDFDocument.create()
const page = pdfDoc.addPage()
const sourcePdfUrl = 'https://pdf-lib.js.org/assets/with_large_page_count.pdf'
const sourcePdf = await fetch(sourcePdfUrl).then((res) => res.arrayBuffer())
// Embed page 74 from the PDF
const [embeddedPage] = await pdfDoc.embedPdf(sourcePdf, 73)
page.drawPage(embeddedPage, {
x: 250,
y: 200,
xScale: 0.5,
yScale: 0.5,
rotate: degrees(30),
opacity: 0.75,
})The options argument accepts both width/height and xScale/yScale
as options. Since each of these options defines the size of the drawn page,
if both options are given, width and height take precedence and the
corresponding scale variants are ignored.
Parameters
embeddedPage: PDFEmbeddedPageThe embedded page to be drawn.options?: PDFPageDrawPageOptionsThe options to be used when drawing the embedded page.
Returns void
drawRectangle
drawRectangle(options?: PDFPageDrawRectangleOptions): voidDraw a rectangle on this page. For example:
import { degrees, grayscale, rgb } from 'pdf-lib'
page.drawRectangle({
x: 25,
y: 75,
width: 250,
height: 75,
rotate: degrees(-15),
borderWidth: 5,
borderColor: grayscale(0.5),
color: rgb(0.75, 0.2, 0.2),
opacity: 0.5,
borderOpacity: 0.75,
})Parameters
options?: PDFPageDrawRectangleOptionsThe options to be used when drawing the rectangle.
Returns void
drawSquare
drawSquare(options?: PDFPageDrawSquareOptions): voidDraw a square on this page. For example:
import { degrees, grayscale, rgb } from 'pdf-lib'
page.drawSquare({
x: 25,
y: 75,
size: 100,
rotate: degrees(-15),
borderWidth: 5,
borderColor: grayscale(0.5),
color: rgb(0.75, 0.2, 0.2),
opacity: 0.5,
borderOpacity: 0.75,
})Parameters
options?: PDFPageDrawSquareOptionsThe options to be used when drawing the square.
Returns void
drawSvgPath
drawSvgPath(path: string, options?: PDFPageDrawSVGOptions): voidDraw an SVG path on this page. For example:
import { rgb } from 'pdf-lib'
const svgPath = 'M 0,20 L 100,160 Q 130,200 150,120 C 190,-40 200,200 300,150 L 400,90'
// Draw path as black line
page.drawSvgPath(svgPath, { x: 25, y: 75 })
// Change border style and opacity
page.drawSvgPath(svgPath, {
x: 25,
y: 275,
borderColor: rgb(0.5, 0.5, 0.5),
borderWidth: 2,
borderOpacity: 0.75,
})
// Set fill color and opacity
page.drawSvgPath(svgPath, {
x: 25,
y: 475,
color: rgb(1.0, 0, 0),
opacity: 0.75,
})
// Draw 50% of original size
page.drawSvgPath(svgPath, {
x: 25,
y: 675,
scale: 0.5,
})Parameters
path: stringThe SVG path to be drawn.options?: PDFPageDrawSVGOptionsThe options to be used when drawing the SVG path.
Returns void
drawText
drawText(text: string, options?: PDFPageDrawTextOptions): voidDraw one or more lines of text on this page. For example:
import { StandardFonts, rgb } from 'pdf-lib'
const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica)
const timesRomanFont = await pdfDoc.embedFont(StandardFonts.TimesRoman)
const page = pdfDoc.addPage()
page.setFont(helveticaFont)
page.moveTo(5, 200)
page.drawText('The Life of an Egg', { size: 36 })
page.moveDown(36)
page.drawText('An Epic Tale of Woe', { size: 30 })
page.drawText(
`Humpty Dumpty sat on a wall \n` +
`Humpty Dumpty had a great fall; \n` +
`All the king's horses and all the king's men \n` +
`Couldn't put Humpty together again. \n`,
{
x: 25,
y: 100,
font: timesRomanFont,
size: 24,
color: rgb(1, 0, 0),
lineHeight: 24,
opacity: 0.75,
},
)Parameters
text: stringThe text to be drawn.options?: PDFPageDrawTextOptionsThe options to be used when drawing the text.
Returns void
getArtBox
getArtBox(): { height: number; width: number; x: number; y: number }Get the rectangle defining this page's ArtBox. For example:
const { x, y, width, height } = page.getArtBox()The ArtBox of a page defines the extent of the page's meaningful content (including potential white space).
The ArtBox's default value is the page's CropBox.
Returns { height: number; width: number; x: number; y: number }
An object defining the lower left corner of the ArtBox and its width & height.
getBleedBox
getBleedBox(): { height: number; width: number; x: number; y: number }Get the rectangle defining this page's BleedBox. For example:
const { x, y, width, height } = page.getBleedBox()The BleedBox of a page defines the region to which the contents of the page shall be clipped when output in a production environment. This may include any extra bleed area needed to accommodate the physical limitations of cutting, folding, and trimming equipment. The actual printed page may include printing marks that fall outside the BleedBox.
The BleedBox's default value is the page's CropBox.
Returns { height: number; width: number; x: number; y: number }
An object defining the lower left corner of the BleedBox and its width & height.
getCropBox
getCropBox(): { height: number; width: number; x: number; y: number }Get the rectangle defining this page's CropBox. For example:
const { x, y, width, height } = page.getCropBox()The CropBox of a page defines the region to which the contents of the page shall be clipped when displayed or printed. Unlike the other boxes, the CropBox does not necessarily represent the physical page geometry. It merely imposes clipping on the page contents.
The CropBox's default value is the page's MediaBox.
Returns { height: number; width: number; x: number; y: number }
An object defining the lower left corner of the CropBox and its width & height.
getHeight
getHeight(): numberGet this page's height. For example:
const height = page.getHeight()This method uses [[PDFPage.getSize]] to obtain the page's size.
Returns number
The height of the page.
getMediaBox
getMediaBox(): { height: number; width: number; x: number; y: number }Get the rectangle defining this page's MediaBox. For example:
const { x, y, width, height } = page.getMediaBox()The MediaBox of a page defines the boundaries of the physical medium on which the page is to be displayed/printed. It may include extended area surrounding the page content for bleed marks, printing marks, etc... It may also include areas close to the edges of the medium that cannot be marked because of physical limitations of the output device. Content falling outside this boundary may safely be discarded without affecting the meaning of the PDF file.
Returns { height: number; width: number; x: number; y: number }
An object defining the lower left corner of the MediaBox and its width & height.
getPosition
getPosition(): { x: number; y: number }Get the default position of this page. For example:
const { x, y } = page.getPosition()Returns { x: number; y: number }
The default position of the page.
getRotation
getRotation(): RotationGet this page's rotation angle in degrees. For example:
const rotationAngle = page.getRotation().angle;Returns Rotation
The rotation angle of the page in degrees (always a multiple of 90 degrees).
getSize
getSize(): { height: number; width: number }Get this page's width and height. For example:
const { width, height } = page.getSize()This method uses [[PDFPage.getMediaBox]] to obtain the page's width and height.
Returns { height: number; width: number }
getTrimBox
getTrimBox(): { height: number; width: number; x: number; y: number }Get the rectangle defining this page's TrimBox. For example:
const { x, y, width, height } = page.getTrimBox()The TrimBox of a page defines the intended dimensions of the finished page after trimming. It may be smaller than the MediaBox to allow for production-related content, such as printing instructions, cut marks, or color bars.
The TrimBox's default value is the page's CropBox.
Returns { height: number; width: number; x: number; y: number }
An object defining the lower left corner of the TrimBox and its width & height.
getWidth
getWidth(): numberGet this page's width. For example:
const width = page.getWidth()This method uses [[PDFPage.getSize]] to obtain the page's size.
Returns number
The width of the page.
getX
getX(): numberGet the default x coordinate of this page. For example:
const x = page.getX()Returns number
The default x coordinate of the page.
getY
getY(): numberGet the default y coordinate of this page. For example:
const y = page.getY()Returns number
The default y coordinate of the page.
moveDown
moveDown(yDecrease: number): voidChange the default position of this page to be further down the y-axis. For example:
page.moveTo(50, 50)
page.drawText('I will be drawn at (50, 50)')
page.moveDown(10)
page.drawText('I will be drawn at (50, 40)')Parameters
yDecrease: numberThe amount by which the page's default position along the y-axis should be decreased.
Returns void
moveLeft
moveLeft(xDecrease: number): voidChange the default position of this page to be further left on the x-axis. For example:
page.moveTo(50, 50)
page.drawText('I will be drawn at (50, 50)')
page.moveLeft(10)
page.drawText('I will be drawn at (40, 50)')Parameters
xDecrease: numberThe amount by which the page's default position along the x-axis should be decreased.
Returns void
moveRight
moveRight(xIncrease: number): voidChange the default position of this page to be further right on the y-axis. For example:
page.moveTo(50, 50)
page.drawText('I will be drawn at (50, 50)')
page.moveRight(10)
page.drawText('I will be drawn at (60, 50)')Parameters
xIncrease: numberThe amount by which the page's default position along the x-axis should be increased.
Returns void
moveTo
moveTo(x: number, y: number): voidChange the default position of this page. For example:
page.moveTo(0, 0)
page.drawText('I will be drawn at the origin')
page.moveTo(0, 25)
page.drawText('I will be drawn 25 units up')
page.moveTo(25, 25)
page.drawText('I will be drawn 25 units up and 25 units to the right')Parameters
x: numberThe new default position on the x-axis for this page.y: numberThe new default position on the y-axis for this page.
Returns void
moveUp
moveUp(yIncrease: number): voidChange the default position of this page to be further up the y-axis. For example:
page.moveTo(50, 50)
page.drawText('I will be drawn at (50, 50)')
page.moveUp(10)
page.drawText('I will be drawn at (50, 60)')Parameters
yIncrease: numberThe amount by which the page's default position along the y-axis should be increased.
Returns void
pushOperators
pushOperators(...operator: PDFOperator[]): voidPush one or more operators to the end of this page's current content stream. For example:
import {
pushGraphicsState,
moveTo,
lineTo,
closePath,
setFillingColor,
rgb,
fill,
popGraphicsState,
} from 'pdf-lib'
// Draw a green triangle in the lower-left corner of the page
page.pushOperators(
pushGraphicsState(),
moveTo(0, 0),
lineTo(100, 0),
lineTo(50, 100),
closePath(),
setFillingColor(rgb(0.0, 1.0, 0.0)),
fill(),
popGraphicsState(),
)Parameters
...operator: PDFOperator[]The operators to be pushed.
Returns void
resetPosition
resetPosition(): voidReset the x and y coordinates of this page to (0, 0). This operation is
often useful after calling [[translateContent]]. For example:
// Shift the page's contents up and to the right by 50 units
page.translateContent(50, 50)
// This text will shifted - it will be drawn at (50, 50)
page.drawText('I am shifted')
// Move back to (0, 0)
page.resetPosition()
// This text will not be shifted - it will be drawn at (0, 0)
page.drawText('I am not shifted')Returns void
scale
scale(x: number, y: number): voidScale the size, content, and annotations of a page.
For example:
page.scale(0.5, 0.5);Parameters
x: numberThe factor by which the width for the page should be scaled (e.g.0.5is 50%).y: numberThe factor by which the height for the page should be scaled (e.g.2.0is 200%).
Returns void
scaleAnnotations
scaleAnnotations(x: number, y: number): voidScale the annotations of a page. This is useful if you want to scale a page with comments or other annotations.
// Scale the content of the page down by 50% in x and y
page.scaleContent(0.5, 0.5);
// Scale the content of the page down by 50% in x and y
page.scaleAnnotations(0.5, 0.5);See also: [[scaleContent]]
Parameters
x: numberThe factor by which the x-axis for the annotations should be scaled (e.g.0.5is 50%).y: numberThe factor by which the y-axis for the annotations should be scaled (e.g.2.0is 200%).
Returns void
scaleContent
scaleContent(x: number, y: number): voidScale the content of a page. This is useful after resizing an existing page. This scales only the content, not the annotations.
For example:
// Bisect the size of the page
page.setSize(page.getWidth() / 2, page.getHeight() / 2);
// Scale the content of the page down by 50% in x and y
page.scaleContent(0.5, 0.5);See also: [[scaleAnnotations]]
Parameters
x: numberThe factor by which the x-axis for the content should be scaled (e.g.0.5is 50%).y: numberThe factor by which the y-axis for the content should be scaled (e.g.2.0is 200%).
Returns void
setArtBox
setArtBox(x: number, y: number, width: number, height: number): voidSet the ArtBox of this page. For example:
const artBox = page.getArtBox()
page.setArtBox(0, 0, 250, 500)
page.setArtBox(artBox.x, artBox.y, 50, 100)
page.setArtBox(15, 5, artBox.width - 50, artBox.height - 100)See [[PDFPage.getArtBox]] for details about what the ArtBox represents.
Parameters
x: numberThe x coordinate of the lower left corner of the new ArtBox.y: numberThe y coordinate of the lower left corner of the new ArtBox.width: numberThe width of the new ArtBox.height: numberThe height of the new ArtBox.
Returns void
setBleedBox
setBleedBox(x: number, y: number, width: number, height: number): voidSet the BleedBox of this page. For example:
const bleedBox = page.getBleedBox()
page.setBleedBox(0, 0, 250, 500)
page.setBleedBox(bleedBox.x, bleedBox.y, 50, 100)
page.setBleedBox(15, 5, bleedBox.width - 50, bleedBox.height - 100)See [[PDFPage.getBleedBox]] for details about what the BleedBox represents.
Parameters
x: numberThe x coordinate of the lower left corner of the new BleedBox.y: numberThe y coordinate of the lower left corner of the new BleedBox.width: numberThe width of the new BleedBox.height: numberThe height of the new BleedBox.
Returns void
setCropBox
setCropBox(x: number, y: number, width: number, height: number): voidSet the CropBox of this page. For example:
const cropBox = page.getCropBox()
page.setCropBox(0, 0, 250, 500)
page.setCropBox(cropBox.x, cropBox.y, 50, 100)
page.setCropBox(15, 5, cropBox.width - 50, cropBox.height - 100)See [[PDFPage.getCropBox]] for details about what the CropBox represents.
Parameters
x: numberThe x coordinate of the lower left corner of the new CropBox.y: numberThe y coordinate of the lower left corner of the new CropBox.width: numberThe width of the new CropBox.height: numberThe height of the new CropBox.
Returns void
setFont
setFont(font: PDFFont): voidChoose a default font for this page. The default font will be used whenever text is drawn on this page and no font is specified. For example:
import { StandardFonts } from 'pdf-lib'
const timesRomanFont = await pdfDoc.embedFont(StandardFonts.TimesRoman)
const helveticaFont = await pdfDoc.embedFont(StandardFonts.Helvetica)
const courierFont = await pdfDoc.embedFont(StandardFonts.Courier)
const page = pdfDoc.addPage()
page.setFont(helveticaFont)
page.drawText('I will be drawn in Helvetica')
page.setFont(timesRomanFont)
page.drawText('I will be drawn in Courier', { font: courierFont })Parameters
font: PDFFontThe default font to be used when drawing text on this page.
Returns void
setFontColor
setFontColor(fontColor: Color): voidChoose a default font color for this page. The default font color will be used whenever text is drawn on this page and no font color is specified. For example:
import { rgb, cmyk, grayscale } from 'pdf-lib'
page.setFontColor(rgb(0.97, 0.02, 0.97))
page.drawText('I will be drawn in pink')
page.setFontColor(cmyk(0.4, 0.7, 0.39, 0.15))
page.drawText('I will be drawn in gray', { color: grayscale(0.5) })Parameters
fontColor: ColorThe default font color to be used when drawing text on this page.
Returns void
setFontSize
setFontSize(fontSize: number): voidChoose a default font size for this page. The default font size will be used whenever text is drawn on this page and no font size is specified. For example:
page.setFontSize(12)
page.drawText('I will be drawn in size 12')
page.setFontSize(36)
page.drawText('I will be drawn in size 24', { fontSize: 24 })Parameters
fontSize: numberThe default font size to be used when drawing text on this page.
Returns void
setHeight
setHeight(height: number): voidResize this page by increasing or decreasing its height. For example:
page.setHeight(500)
page.setHeight(page.getWidth() + 100)
page.setHeight(page.getWidth() - 100)This method uses [[PDFPage.setSize]] to set the page's height.
Parameters
height: numberThe new height of the page.
Returns void
setLineHeight
setLineHeight(lineHeight: number): voidChoose a default line height for this page. The default line height will be used whenever text is drawn on this page and no line height is specified. For example:
page.setLineHeight(12);
page.drawText('These lines will be vertically \n separated by 12 units')
page.setLineHeight(36);
page.drawText('These lines will be vertically \n separated by 24 units', {
lineHeight: 24
})Parameters
lineHeight: numberThe default line height to be used when drawing text on this page.
Returns void
setMediaBox
setMediaBox(x: number, y: number, width: number, height: number): voidSet the MediaBox of this page. For example:
const mediaBox = page.getMediaBox()
page.setMediaBox(0, 0, 250, 500)
page.setMediaBox(mediaBox.x, mediaBox.y, 50, 100)
page.setMediaBox(15, 5, mediaBox.width - 50, mediaBox.height - 100)See [[PDFPage.getMediaBox]] for details about what the MediaBox represents.
Parameters
x: numberThe x coordinate of the lower left corner of the new MediaBox.y: numberThe y coordinate of the lower left corner of the new MediaBox.width: numberThe width of the new MediaBox.height: numberThe height of the new MediaBox.
Returns void
setRotation
setRotation(angle: Rotation): voidRotate this page by a multiple of 90 degrees. For example:
import { degrees } from 'pdf-lib'
page.setRotation(degrees(-90))
page.setRotation(degrees(0))
page.setRotation(degrees(90))
page.setRotation(degrees(180))
page.setRotation(degrees(270))Parameters
angle: RotationThe angle to rotate this page.
Returns void
setSize
setSize(width: number, height: number): voidResize this page by increasing or decreasing its width and height. For example:
page.setSize(250, 500)
page.setSize(page.getWidth() + 50, page.getHeight() + 100)
page.setSize(page.getWidth() - 50, page.getHeight() - 100)Note that the PDF specification does not allow for pages to have explicit widths and heights. Instead it defines the "size" of a page in terms of five rectangles: the MediaBox, CropBox, BleedBox, TrimBox, and ArtBox. As a result, this method cannot directly change the width and height of a page. Instead, it works by adjusting these five boxes.
This method performs the following steps:
- Set width & height of MediaBox.
- Set width & height of CropBox, if it has same dimensions as MediaBox.
- Set width & height of BleedBox, if it has same dimensions as MediaBox.
- Set width & height of TrimBox, if it has same dimensions as MediaBox.
- Set width & height of ArtBox, if it has same dimensions as MediaBox.
This approach works well for most PDF documents as all PDF pages must have a MediaBox, but relatively few have a CropBox, BleedBox, TrimBox, or ArtBox. And when they do have these additional boxes, they often have the same dimensions as the MediaBox. However, if you find this method does not work for your document, consider setting the boxes directly:
- [[PDFPage.setMediaBox]]
- [[PDFPage.setCropBox]]
- [[PDFPage.setBleedBox]]
- [[PDFPage.setTrimBox]]
- [[PDFPage.setArtBox]]
Parameters
width: numberThe new width of the page.height: numberThe new height of the page.
Returns void
setTrimBox
setTrimBox(x: number, y: number, width: number, height: number): voidSet the TrimBox of this page. For example:
const trimBox = page.getTrimBox()
page.setTrimBox(0, 0, 250, 500)
page.setTrimBox(trimBox.x, trimBox.y, 50, 100)
page.setTrimBox(15, 5, trimBox.width - 50, trimBox.height - 100)See [[PDFPage.getTrimBox]] for details about what the TrimBox represents.
Parameters
x: numberThe x coordinate of the lower left corner of the new TrimBox.y: numberThe y coordinate of the lower left corner of the new TrimBox.width: numberThe width of the new TrimBox.height: numberThe height of the new TrimBox.
Returns void
setWidth
setWidth(width: number): voidResize this page by increasing or decreasing its width. For example:
page.setWidth(250)
page.setWidth(page.getWidth() + 50)
page.setWidth(page.getWidth() - 50)This method uses [[PDFPage.setSize]] to set the page's width.
Parameters
width: numberThe new width of the page.
Returns void
translateContent
translateContent(x: number, y: number): voidTranslate this page's content to a new location on the page. This operation is often useful after resizing the page with [[setSize]]. For example:
// Add 50 units of whitespace to the top and right of the page
page.setSize(page.getWidth() + 50, page.getHeight() + 50)
// Move the page's content from the lower-left corner of the page
// to the top-right corner.
page.translateContent(50, 50)
// Now there are 50 units of whitespace to the left and bottom of the pageSee also: [[resetPosition]]
Parameters
x: numberThe new position on the x-axis for this page's content.y: numberThe new position on the y-axis for this page's content.
Returns void