Pdflib Syntax Drawing

pdf-lib Drawing Operations

Draw shapes, lines, and SVG paths on PDF pages with full control over colors, borders, opacity, and rotation.

Critical Rules

• Color values are 0.0-1.0, NOT 0-255. rgb(1, 0, 0) is red. rgb(255, 0, 0) silently produces wrong output.
• drawEllipse uses xScale/yScale, NOT width/height. These define radii, not diameters.
• drawLine uses thickness, NOT borderWidth. It also uses dashArray/dashPhase (not borderDashArray/borderDashPhase).
• drawLine uses start/end point objects, NOT x/y.
• drawCircle and drawSquare use size, NOT width/height or radius.
• Coordinate origin is bottom-left. Y increases upward. To draw near the top, use y: height - offset.
• All draw methods are synchronous. No await needed on page.drawRectangle(), etc.
• ALWAYS import color constructors explicitly: import { rgb, cmyk, grayscale } from 'pdf-lib'

Required Imports

import {
  PDFDocument,
  rgb,           // rgb(r, g, b) — all 0.0-1.0
  cmyk,          // cmyk(c, m, y, k) — all 0.0-1.0
  grayscale,     // grayscale(g) — 0.0 black, 1.0 white
  degrees,       // degrees(45) → Rotation
  radians,       // radians(Math.PI / 4) → Rotation
  BlendMode,     // BlendMode.Normal, .Multiply, etc.
  LineCapStyle,  // LineCapStyle.Butt, .Round, .Square
} from 'pdf-lib'

Shape Decision Tree

What shape do you need?
├── Filled/stroked box?
│   ├── Square (equal sides) → page.drawSquare({ size })
│   └── Rectangle → page.drawRectangle({ width, height })
├── Rounded/circular?
│   ├── Circle → page.drawCircle({ size })  // size = diameter
│   └── Ellipse → page.drawEllipse({ xScale, yScale })  // radii
├── Line between two points?
│   └── page.drawLine({ start: {x,y}, end: {x,y}, thickness })
└── Complex/custom shape?
    └── page.drawSvgPath('M 0,0 L 100,100 ...', { scale, color })

Quick Reference: Color Constructors

Color type: Color = Grayscale | RGB | CMYK

Common Colors

const black   = rgb(0, 0, 0)
const white   = rgb(1, 1, 1)
const red     = rgb(1, 0, 0)
const green   = rgb(0, 1, 0)
const blue    = rgb(0, 0, 1)
const yellow  = rgb(1, 1, 0)
const gray50  = grayscale(0.5)

Quick Reference: All Shape Methods

drawRectangle

page.drawRectangle({
  x: 50, y: 50,
  width: 200, height: 100,
  color: rgb(0.2, 0.4, 0.8),        // fill color
  borderColor: rgb(0, 0, 0),        // stroke color
  borderWidth: 2,                    // stroke thickness
  opacity: 0.9,                     // fill opacity 0.0-1.0
  borderOpacity: 1,                 // stroke opacity 0.0-1.0
  rotate: degrees(15),              // rotation
  borderDashArray: [6, 3],          // dashed border: 6pt dash, 3pt gap
  borderDashPhase: 0,               // dash offset
  borderLineCap: LineCapStyle.Round, // cap style
  blendMode: BlendMode.Normal,      // blending
})

drawSquare

page.drawSquare({
  x: 50, y: 50,
  size: 100,                        // side length (NOT width/height)
  color: rgb(1, 0.8, 0),
  borderColor: rgb(0, 0, 0),
  borderWidth: 1.5,
  rotate: degrees(45),
  opacity: 1,
  borderOpacity: 1,
  borderDashArray: [4, 2],
  borderDashPhase: 0,
  borderLineCap: LineCapStyle.Butt,
  blendMode: BlendMode.Normal,
})

drawCircle

page.drawCircle({
  x: 200, y: 300,                   // center point
  size: 80,                         // diameter (NOT radius)
  color: rgb(0.9, 0.1, 0.1),
  borderColor: rgb(0, 0, 0),
  borderWidth: 2,
  opacity: 0.7,
  borderOpacity: 1,
  borderDashArray: [5, 5],
  borderDashPhase: 0,
  borderLineCap: LineCapStyle.Round,
  blendMode: BlendMode.Normal,
})

drawEllipse

page.drawEllipse({
  x: 250, y: 400,                   // center point
  xScale: 120,                      // horizontal RADIUS (NOT width)
  yScale: 60,                       // vertical RADIUS (NOT height)
  color: rgb(0.3, 0.7, 0.3),
  borderColor: rgb(0, 0, 0),
  borderWidth: 1,
  rotate: degrees(30),
  opacity: 0.8,
  borderOpacity: 1,
  blendMode: BlendMode.Normal,
})

drawLine

CRITICAL: drawLine uses DIFFERENT option names than other shapes.

page.drawLine({
  start: { x: 50, y: 500 },         // start point object
  end: { x: 400, y: 500 },          // end point object
  thickness: 2,                      // NOT borderWidth
  color: rgb(0, 0, 0),              // line color (NOT borderColor)
  opacity: 1,
  dashArray: [10, 5],               // NOT borderDashArray
  dashPhase: 0,                     // NOT borderDashPhase
  lineCap: LineCapStyle.Butt,        // NOT borderLineCap
  blendMode: BlendMode.Normal,
})

drawSvgPath

page.drawSvgPath(
  'M 0,20 L 100,160 Q 130,200 150,120 C 190,-40 200,200 300,150 L 400,90',
  {
    x: 50, y: 700,                  // offset position
    color: rgb(0.8, 0.2, 0.2),      // fill color
    borderColor: rgb(0, 0, 0),      // stroke color
    borderWidth: 2,                  // stroke width
    opacity: 1,
    borderOpacity: 1,
    scale: 0.5,                     // scale factor
    rotate: degrees(0),
    blendMode: BlendMode.Normal,
  }
)

Drawing Options Cross-Reference Table

Enums Reference

BlendMode

BlendMode.Normal | Multiply | Screen | Overlay | Darken | Lighten | ColorDodge | ColorBurn | HardLight | SoftLight | Difference | Exclusion

LineCapStyle

LineJoinStyle

Rotation

import { degrees, radians } from 'pdf-lib'

// Use degrees() or radians() to create Rotation values
page.drawRectangle({ x: 100, y: 100, width: 80, height: 40, rotate: degrees(45) })
page.drawRectangle({ x: 300, y: 100, width: 80, height: 40, rotate: radians(Math.PI / 6) })

SVG Path Commands Reference

Lowercase variants (m, l, h, v, c, q, a, z) use relative coordinates.

Reference Links

• Complete method signatures
• Code examples
• Anti-patterns and common mistakes