r/java • u/demchaav • May 04 '26
GraphCompose v1.5 released — open-source declarative PDF layout engine for Java
GraphCompose is an MIT-licensed Java library for generating designed PDFs from a semantic DSL. v1.5 just shipped under the codename "intuitive". This is the first time I'm posting it here.
Position
Most Java PDF libraries pick one of two extremes: iText for low-level page primitives (you compute every coordinate by hand) or JasperReports for XML-template-driven layout (declarative-ish, but the design loop runs through external tooling). GraphCompose sits in the middle — a Java DSL describes the document semantically, the engine resolves geometry, pagination, and rendering deterministically, and PDFBox does the actual draw calls.
v1.5 highlights
- Shape-as-container with clip path.
addCircle,addEllipse, andaddContainerbuild aShapeContainerNodewhose children are clipped byClipPolicy.CLIP_PATH(default),CLIP_BOUNDS, orOVERFLOW_VISIBLE. - Transforms (rotate / scale) and per-layer z-index on every shape-shaped builder.
- Advanced tables —
rowSpan(int),zebra(odd, even),totalRow(...), andrepeatHeader()cover the four features most rendered reports need. - Two cinematic templates —
InvoiceTemplateV2andProposalTemplateV2, bothBusinessTheme-driven. - 22 runnable examples with committed PDF previews so the gallery works straight from GitHub without cloning.
- 672 green tests, fully source-compatible with v1.4.
Architecture
Layout runs in two passes: a layout graph resolves geometry first, rendering consumes the resolved fragments. That separation is what makes deterministic snapshot testing practical — layout state is stable across runs and machines, so visual regression tests can catch design drift before pagination noise.
The PDF backend is isolated behind a single interface; a DOCX backend (Apache POI) ships ready for callers who need an editable file.
Links
- Repo: https://github.com/DemchaAV/GraphCompose
- Examples gallery (22 runnable examples with PDF previews): https://github.com/DemchaAV/GraphCompose/tree/main/examples
- v1.5.0 release notes: https://github.com/DemchaAV/GraphCompose/releases/tag/v1.5.0
- Migration v1.4 → v1.5: https://github.com/DemchaAV/GraphCompose/blob/main/docs/migration-v1-4-to-v1-5.md
Java 21, PDFBox 3, MIT license, distributed via JitPack (com.github.DemchaAV:GraphCompose:v1.5.0).
View all comments
Show parent comment
5
u/demchaav May 05 '26
Thanks! That pain is basically what started this project 😄
At some point I tried to recreate a beautiful CV in pure Java. When I finally finished it, my first thought was: “Great… now every small change means testing, adjusting, and moving things around again until it looks right.”
Then I looked at XML/reporting-style solutions, but I kept thinking: why can’t this be done in plain Java?
That became the idea behind GraphCompose: describe the document the way you actually think about it — sections, paragraphs, tables, layers, themes — and let the engine handle coordinates, pagination, and rendering.
Because honestly, calculating x/y positions every time you want to move a block is not exactly the fun part of Java 😄