Phase 4 - Smart page-break intelligence and advanced pagination controls
S
Saurabh Choudhary
This phase focuses on making pagination smarter and more predictable for complex documents without breaking the existing public API.
Planned work:
- Add smart split controls
Add data-pdf-split="avoid"
Keep a block together when it fits on one page
Avoid awkward page breaks inside important sections
Preserve existing behavior when the attribute is not used
- Add container-aware splitting
Add data-pdf-split="container"
Allow large containers to split across pages intelligently
Preserve child structure where possible
Avoid unnecessary blank space
- Add explicit page-break controls
Add break-before support
Add break-after support
Keep compatibility with existing html2pdf__page-break behavior
Make page-break rules consistent across supported render modes
- Handle oversized elements safely
Detect elements larger than a single PDF page
Prevent infinite pagination loops
Fall back to safe splitting when a block cannot fit on one page
Keep generation recoverable for extreme layouts
- Improve table pagination
Support repeated table headers across pages
Reduce broken rows where possible
Improve long-table readability
Keep behavior predictable for large datasets
- Add pagination diagnostics
Add an optional pagination debug overlay
Show detected page boundaries
Highlight forced and automatic breaks
Help developers understand why content moved to a new page
- Add page-break diagnostic events and metadata
Expose useful pagination information for debugging
Report split decisions when diagnostics are enabled
Keep diagnostics opt-in
Avoid changing generated PDF output by default
- Expand regression and stress coverage
Add unit tests for new pagination rules
Add browser E2E coverage
Test portrait and landscape layouts
Test long documents and stress presets
Verify existing users are not affected
Primary goals:
improve pagination quality
reduce awkward content splitting
improve long-document reliability
improve table handling
give developers more control over page breaks
make pagination easier to debug
preserve backward compatibility
avoid unnecessary runtime overhead when advanced pagination features are not used
This phase should be implemented incrementally with regression tests after each step.
Status: Planned
S
Saurabh Choudhary
Released in vue-pdf-export 1.2.0: smart keep-together/container splitting, explicit page breaks, oversized-content fallback, repeated table headers and opt-in pagination diagnostics. This release also improves custom document layers, PDF composition and generation efficiency. Existing public APIs remain supported. Try the playground and read the documentation for configuration and renderer limits.
S
Saurabh Choudhary
Smart page-break intelligence and advanced pagination controls are implemented and undergoing final release validation.
This update adds:
- data-pdf-split="avoid"to keep fitting blocks together.
- data-pdf-split="container"for child-aware splitting, nested spacing and continuation frames.
- Explicit CSS page breaks with legacy html2pdf__page-breakcompatibility.
- Safe fallback for oversized elements, with diagnostics instead of unbounded pagination retries.
- Improved table row boundaries and repeated table headers on continuation pages.
- Opt-in pagination overlays, break events, warnings and completion metadata.
- Shared page geometry across supported formats and orientations.
- Header/footer object options and Vue slots, PDF composition, export performance improvements and a refreshed playground.
Unit coverage and production builds have passed. Browser and stress test files are available, but final browser/visual acceptance for the latest changes is still pending. Oversized content and complex CSS/table structures may require fallback splitting; this update does not promise that every possible layout stays unbroken.
Target release:
1.2.0
. I will post the published version and final verification results here when the release is ready.