Skip to main content

Choosing an API

a11ydocs offers a few layers, from absolute drawing to automatic multi-page layout. This page maps common goals to the right tool so you don't have to scan the whole reference.

Text​

GoalUse
Draw one line at an exact spotpage.text(text, options)
Wrap a paragraph to a widthpage.textBlock(text, options)
Mixed fonts/sizes/colors/links on the same linepage.richText(runs, options)
Inline link/highlight over a substring of a uniform paragraphparagraph + annotations (see Forms and Annotations)
Flowing content with auto-pagination, headers/footersrenderTemplate() or the PdfFlow cursor
Whole document as one serializable value (config/API/LLM)renderDocumentJson(document)
Know a size before drawingdoc.measureText / measureTextBlock / measureRichText
Draw and stack manually using the consumed heightpage.placeText / page.placeTextBlock (return endY)

Manual vertical stacking​

text/textBlock/richText return the page (for chaining) and don't tell you where the text ended. When you're laying out by hand and need the next y, use the place* variants, which draw and return metrics:

let y = 760;
y = page.placeTextBlock("Intro paragraph…", { x: 56, y, width: 480 }).endY - 8;
y = page.placeTextBlock("Next paragraph…", { x: 56, y, width: 480 }).endY - 8;

For anything beyond a few blocks, prefer the flow/template APIs — they track the cursor, wrap, and paginate for you.

Graphics and images​

GoalUse
Rectangle / line / circle / ellipsepage.rect / line / circle / ellipse
Arbitrary vector geometrypage.path(commands, style)
Embed an image, format knownpage.png / page.jpeg / … (see Images)
Embed an image, format unknownpage.image(data, options)
SVGpage.svg(data, options)
Default stroke/fill for many shapescreateDocument({ shapeDefaults })

Color, fonts, units, coordinates​

GoalUse
Colorrgb(), cmyk(), gray(), hex(), or a named color string / color()
Bold/italic, font familiesregisterFontFamily() + bold/italic flags
Underline / strike-throughunderline / strike text options
Physical unitsmm(), cm(), inch(), pt()
Document-wide text defaultscreateDocument({ defaults })
y grows downward from the topaddPage({ origin: "top-left" }) (see Coordinate system)

Structure, forms, and assembly​

GoalUse
Tablespage.table(rows, options) or a table template block
Listspage.list(items, options)
Form fieldspage.textField / checkBox / choiceField / radioGroup / pushButton / signatureField (see Forms and Annotations)
Tagged structure for accessibilitypage.container() / page.structure() (see Accessibility)
Edit an existing PDFeditDocument() / parseDocument()
Merge / split / extract / append pagesPage Assembly helpers

Page vs flow vs template​

  • Page methods (page.text, page.rect, …) — you place everything at explicit coordinates. Most control; you manage layout.
  • Flow (page.flow()) — a cursor that advances as you add blocks; wraps and (with an overflow handler) continues across columns/pages. Good for one-off flowing sections.
  • Template (doc.renderTemplate()) — declarative blocks with stylesheets, headers/footers, page numbers, and automatic pagination. Best for reports and documents.

Start with templates for documents, drop to flow for a flowing region inside a hand-laid page, and use page methods for pixel-precise placement.