Migrating from PDF
Mapping PDF concepts onto their Joy DOM equivalents.
PDF is fixed-page, binary, and read-mostly. Joy DOM is responsive, JSON, and editable. The translation is not always 1:1 - sometimes the Joy DOM equivalent is a different idea, not the same idea expressed differently. This page walks through the common mappings.
Concept map
| PDF concept | Joy DOM equivalent |
|---|---|
| Pages (fixed size) | One layout tree per document. Print breakpoints adjust for paper output. |
| Text frames | p, h1–h6, and span nodes. |
| Layout grids | Nested div with flexDirection: "row" or "column" and gap. |
| Embedded fonts | fontFamily in the spec; renderers ensure the font is available on the platform. |
| Tagged accessibility structure | Semantic HTML-like node types (h1, p, etc.) inherit their accessibility role. |
| Forms | Custom nodes (text-field, checkbox) registered with the renderer. |
| Bookmarks / outline | Use node ids and h1–h6 headings; render the outline from the JSON. |
| Annotations / comments | Out of scope. Layer on top of the rendered document if your app needs them. |
| Print vs screen | Breakpoint with { type: "type", value: "print" }. |
| Encryption / signing | Out of scope. Sign or encrypt the JSON document at the transport layer. |
A worked example
A typical PDF invoice has a fixed-page layout: 8.5"×11", absolute-positioned text frames, embedded fonts. The same invoice in Joy DOM:
- Replace absolute-positioned text frames with nested
divflex containers - see Invoice recipe. - Replace the fixed page size with a
maxWidthon the outer container and let the renderer adapt the height. - Replace the embedded-font dependency with a
fontFamilyreference - the renderer resolves it on the platform. - Add a print breakpoint that tightens padding and drops the background colors for paper.
The JSON is shorter than the underlying PDF object stream, and it survives diffing in version control.
Things PDF does that Joy DOM does not (yet)
Honest limitations
Joy DOM is not a one-for-one PDF replacement. The list below is what Joy DOM does not currently match. Each is on the roadmap or explicitly out of scope.
- Pixel-exact reproduction. PDFs are designed for archival fidelity; Joy DOM prioritizes responsive native rendering.
- Embedded raster fonts. Renderers use platform fonts; embedding is not supported.
- PDF/A archival profile. No archival profile exists yet.
- Form data round-trip. Custom form-field components can capture input, but the protocol for persisting it is your renderer's job.
Generating a PDF from Joy DOM
For users who still need a PDF artifact:
- Browser print preview ⇒ "Save as PDF" is the simplest path. Combine with your print breakpoint.
- Headless browsers (Puppeteer, Playwright) point at a rendered Joy DOM page and call
page.pdf(). - A dedicated
@joy-dom/pdfrenderer is planned but not shipped.
Where next
- Invoice recipe - a worked Joy DOM document for a typical PDF use case.
- Specification - every supported property and breakpoint condition.
- Embedding in React - get Joy DOM running in an app today.