boxpdf

@boxpdf/writer

A box-layout DSL over pdf-lib. Implemented in portable JavaScript, it runs in Node 20+, Cloudflare Workers, Deno, and browsers.

Live gallery: https://earonesty.github.io/boxpdf/

Related repos: boxpdf-html (HTML → BoxPDF) and streaming-pdf-reader (PDF → document model, HTML, and structured data).

import { cleanTheme, flowToPdf, hline, hstack, standardFonts, text, vstack } from "@boxpdf/writer";

const bytes = await flowToPdf(async (pdf) => { const { font, bold } = await standardFonts(pdf); const theme = cleanTheme({ font, bold });

return [ vstack({ gap: 8 }, text("Receipt #18472", theme.type.h1), text("May 14, 2026", theme.type.caption) ), hline(theme.hr), hstack({ gap: 16, justify: "between", width: 515 }, text("Wool socks", theme.type.body), text("$28.00", { ...theme.type.body, font: bold, align: "right", width: 80 }) ) ]; });

flowToPdf owns the document lifecycle and returns the saved bytes. standardFonts embeds the built-in Helvetica family (regular, bold, italic, bold-italic) in one call.

Prefer to manage the document yourself? The explicit path still works.

import { PDFDocument, StandardFonts } from "pdf-lib";

import { cleanTheme, renderFlow, text, vstack } from "@boxpdf/writer";

const pdf = await PDFDocument.create(); const font = await pdf.embedFont(StandardFonts.Helvetica); const bold = await pdf.embedFont(StandardFonts.HelveticaBold); const theme = cleanTheme(font, bold);

await renderFlow(pdf, [ vstack({ gap: 8 }, text("Receipt #18472", theme.type.h1), text("May 14, 2026", theme.type.caption) ) ]);

const bytes = await pdf.save();

renderFlow(pdf, nodes, options) paginates into a document you own and returns { pages } — reach for it when you need multiple render passes, the page objects, or custom save() options. boxpdf re-exports PDFDocument and StandardFonts for this explicit lifecycle.

Install

npm install @boxpdf/writer pdf-lib

pdf-lib is a peer dependency.

Legacy package name

The original boxpdf package remains supported and is published from the same build at the same version. Existing imports and the boxpdf CLI continue to work unchanged:

npm install boxpdf pdf-lib

New projects should use @boxpdf/writer. Both package names expose the same API, and both provide the boxpdf command.

What it does

• Declarative layout primitives: vstack, hstack, text, image, hline, vline, spacer, flex, keepTogether, link, svgPath, table.
• Layout-aware AcroForm fields: text, checkbox, radio, dropdown, option-list, and push-button widgets.
• Padding, margin, background, background images, borders, borderRadius, overflow clipping, flex-grow, flex-shrink, justify, align.
• Rich paragraphs with mixed inline runs, inline replaced nodes, hard breaks, hanging indents, and optional paragraph floats.
• Word wrapping with maxLines truncation, optional breakWords, and no-wrap control.
• Themes: cleanTheme, stripeTheme, editorialTheme, brutalistTheme.
• Multi-page flow with per-page headers and footers, stack fragmentation, and table row fragmentation.
• Streaming generation for memory-bounded output.
• PDF link annotations, text decorations, document metadata.
• ~7 KB minified core. Custom fonts pull in @pdf-lib/fontkit only when you call loadFont or embedInter.

Templates

Files in templates/ cover receipts, boarding passes, resumes, order confirmations, and certificates. Each is a single file.

Scaffold one into your app with the CLI:

npx boxpdf init receipt --out src/pdf/receipt.ts

npx boxpdf list

The CLI also ships a resource-only MCP server for agents:

claude mcp add boxpdf -- npx -y boxpdf mcp

Themes

import { cleanTheme, editorialTheme, standardFonts } from "@boxpdf/writer";

const theme = cleanTheme(await standardFonts(pdf)); // Helvetica const serif = editorialTheme(await standardFonts(pdf, "times")); // serif + italic slot

Every theme factory accepts either a { font, bold, italic? } object — which is exactly what standardFonts(pdf) and embedInter(pdf) return — or the legacy positional fonts:

cleanTheme({ font, bold })            // or cleanTheme(font, bold)

stripeTheme({ font, bold }) editorialTheme({ font, bold, italic }) // or editorialTheme(font, bold, italic) brutalistTheme({ font, bold }) // courier regular + bold

standardFonts(pdf, family) takes "helvetica" (default), "times", or "courier" and returns { font, bold, italic, boldItalic }. Every theme exposes the same shape: colors, spacing, radii, type, card, hr.

API

Containers

• vstack(style, ...children). Vertical layout.
• hstack(style, ...children). Horizontal layout.
• keepTogether({ gap?, margin? }, ...children). Paginates atomically.

Container style:

Leaves

• text(content, { size, font, color?, align?, width?, lineHeight?, maxLines?, underline?, strikethrough?, margin? }). Word-wraps when width is set. Truncates with ellipsis when maxLines is set. Default lineHeight uses the font's full height, including descenders.
• paragraph({ width?, align?, lineHeight?, margin?, paddingLeft?, textIndent?, wrap?, floats? }, ...runs). Mixed inline text runs and atomic inline nodes that wrap together as one paragraph. Use run(text, style), linkRun(text, style, href), and inlineNode(node, { verticalAlign?, href? }). Newlines in runs create hard breaks; wrap: false disables soft wrapping.
• image(pdfImage, { width, height, margin? }). Takes an already-embedded PDFImage.
• imageFit(pdfImage, { width, height, fit?, margin? }). Draws an image centered in a fixed rectangle, scaled to contain (default) or cover with clipping.
• spacer(size, { grow? }) / flex(weight = 1). Fixed or growing gap.
• hline({ color, thickness?, width?, margin? }).
• vline({ color, thickness?, height?, margin? }).
• link({ href }, child). Wraps a child and registers a PDF Link annotation over its rendered bounding box.
• table({ columns, rows, ... }). Fixed / auto / fractional columns with header/footer rows, dividers, styled cells, and row-level page fragmentation under renderFlow. Cells can be plain nodes or { content, colSpan?, padding?, background?, border?, borderSides?, borderRadius?, align?, valign? }.

AcroForm fields

Form widgets are atomic layout nodes, so they work inside stacks, tables, pagination, and streamed documents without manual page coordinates.

import {

checkbox, dropdown, flowToPdf, standardFonts, text, textField, vstack } from "@boxpdf/writer";

const bytes = await flowToPdf(async (pdf) => { const { font } = await standardFonts(pdf); return [ vstack({ gap: 10 }, text("Registration", { size: 18, font }), textField({ name: "person.name", width: 260, height: 26, font, fontSize: 11, required: true }), dropdown({ name: "person.state", width: 140, height: 26, font, options: ["CA", "NY", "WA"] }), checkbox({ name: "terms.accepted", width: 16, height: 16, required: true }) ) ]; });

• textField({ name, width, height, ... }). Supports an initial value, multiline, password, maxLength, combed, alignment, and shared field flags and appearance options. Password text fields are non-exportable by default unless exported: true is explicitly set.
• checkbox({ name, width, height, checked? }).
• radioOption({ name, option, width, height, selected? }). Nodes with the same name form one radio group.
• dropdown({ name, options, width, height, selected?, editable?, sorted? }). Kept single-select for consistent viewer behavior.
• optionList({ name, options, width, height, selected?, multiselect?, sorted? }).
• button({ name, label, width, height, ... }). Creates a portable push-button widget and appearance; BoxPDF does not attach PDF JavaScript or submit actions. Standard SubmitForm actions are reader-dependent and browser viewers may block submissions from local PDFs by origin policy.

All fields accept margin, alignSelf, readOnly, required, exported, hidden, backgroundColor, borderColor, and borderWidth. Text-bearing fields also accept font, fontSize, and textColor. Field names are document-global. Reusing a name adds another widget for the same logical field; reusing it for a different field type throws. Password text fields default to exported: false, so mark exported: true to permit submission/export intentionally. Forms work with ordinary, streamed, and encrypted output; use the encryption fillForms permission to control whether conforming readers allow changes. For shared logical fields, text, dropdown, and option-list initialization state (value, options, and initial selected) is fixed by the first node. Radio-group flags (offToggleable, mutuallyExclusive) are also first-node-only. selected: true on a radioOption marks that option, while selected: false does not clear any existing selection.

Use getFormValues(pdf), setFormValues(pdf, values), and flattenForm(pdf) when working with a caller-owned PDFDocument. When updating non-WinAnsi text, pass the embedded font as { font } to setFormValues or flattenForm so pdf-lib regenerates the appearances with that font.

AcroForm widgets are PDF annotations rather than page drawing operations. They therefore cannot be placed inside transformed BoxPDF ancestors; BoxPDF throws instead of emitting a misplaced widget. XFA, signature fields, PDF JavaScript, and cryptographic signing are outside the core form layer.

Rendering

• flowToPdf(build, options?). The shortest path to bytes. Creates a PDFDocument, hands it to your build(pdf) callback (embed fonts/images there and ret