[Bug]: Missing Automatic Pagination Support for Page-Based Editing in Tiptap

[ALGOREX-PH]

Affected Packages

Editor

Version(s)

2.11.5

Bug Description

📝 Description of the Issue
I’m currently building a page-based document editor using Tiptap, and I’ve encountered a major limitation: Tiptap doesn’t support automatic pagination. This is a critical feature for applications where users are expected to write across multiple page layouts—like resumes, formal reports, academic papers, or any print-ready document format.

Right now, as I type and fill up a styled page container (for example, a div sized like an A4 sheet), Tiptap allows the content to overflow rather than automatically pushing excess content onto a new page. Similarly, if I delete enough text, content from the next page doesn’t pull back to fill the previous one. This breaks the illusion of a natural, flowing document and disrupts both UX and layout integrity.

This kind of functionality is standard in editors like Google Docs, and I believe Tiptap should support it natively or at least provide hooks or extensions to make it feasible to implement.

✅ Expected Behavior
What I expect from Tiptap in a page-based editor setup:

It should automatically detect when a page is full and move the remaining content to a new, styled page container.

When content is deleted and space becomes available, content from the next page should move back up to fill the gap (reverse pagination).

The layout should:

Preserve formatting such as paragraphs, headings, lists, and tables

Avoid breaking paragraphs across pages awkwardly

Respect defined margins and prevent layout glitches

Dynamically reflow when the user adjusts font size, spacing, or window size

❌ Actual Behavior
Here’s what I’m seeing instead:

There’s no built-in mechanism for handling page boundaries.

Content simply overflows the page div, making it visually and functionally break from a proper paginated layout.

There’s no reverse flow of content when removing text.

I'm left trying to hack together pagination logic manually, which is hard to maintain and fragile—especially with more complex content like tables, images, or embeds.

Attempted CSS or observer-based workarounds only simulate pagination visually but do not enforce content structure between pages.

🧪 Steps to Reproduce
I styled a Tiptap editor inside a fixed-height container (e.g., simulating an A4 page with 1-inch margins).

I typed enough paragraphs to exceed the container’s visible space.

The content just continued down—no new page was created.

I tried deleting some content—nothing moved back up.

I added tables and images—these overlapped page boundaries, further breaking layout expectations.

📌 Why This Matters
This issue has been a blocker in building:

Google Docs-style document editors

Resume or CV builders that require strict layout control

Print-preview or PDF-generation tools

Education and enterprise applications that involve formal, multi-page documents

Without this feature:

The user experience suffers, since the document no longer behaves like a document.

Printed output becomes unpredictable or broken.

I have to write complex, fragile logic to manage pagination myself—something that ideally should be abstracted by the library.

💡 Suggested Enhancement
To fix this, I suggest adding an official pagination system or extension with the following features:

1. Layout-aware Pagination Module
   Detect the height of content blocks within a styled page container.

Push excess nodes to the next container when a page is full.

2. Content Flow Manager
   Dynamically shift nodes forward or backward across pages based on content changes.

3. Page-Aware Node Rendering
   Prevent splitting large elements across pages.

Add page-break options for blocks like headings, paragraphs, images, etc.

4. Virtualized Page Renderer
   Render only a few pages at a time (like infinite scroll) for performance, especially in long documents.

5. Hooks or Events
   Provide lifecycle hooks when a page is added or removed.

Let developers customize pagination behavior or style it with their own logic.

📎 Temporary Workarounds I Tried (and Their Issues)
CSS max-height & overflow: Only hides content but doesn’t trigger a true content move.

Manual content splitting by node index: Unscalable and breaks with large or dynamic elements.

ResizeObserver tracking: Inconsistent results when used with real-time typing and image/media content.

None of these offer a solid, production-ready solution for true pagination.

📷 Visual Reference (What I’m Hoping For)
I type until Page 1 is full → content automatically flows into Page 2.

I delete from Page 1 → Page 2 content moves back up seamlessly.

Each page remains visually and structurally distinct—just like in Google Docs or Microsoft Word.

🔚 Conclusion
In my opinion, the lack of automatic pagination is one of the few but significant gaps in Tiptap for page-based editors. Adding true automatic pagination and dynamic content flow across pages would significantly boost Tiptap’s usability for a wide range of real-world applications.

I’d love to see this prioritized—whether as a core feature, a built-in extension, or even guidance on how to implement this in a maintainable way. I'm happy to help test or contribute if this becomes part of the roadmap.

Thanks for the great work on Tiptap!

Browser Used

Chrome

Code Example URL

No response

Expected Behavior

✅ Expected Behavior
What I expect from Tiptap in a page-based editor setup:

It should automatically detect when a page is full and move the remaining content to a new, styled page container.

When content is deleted and space becomes available, content from the next page should move back up to fill the gap (reverse pagination).

The layout should:

Preserve formatting such as paragraphs, headings, lists, and tables

Avoid breaking paragraphs across pages awkwardly

Respect defined margins and prevent layout glitches

Dynamically reflow when the user adjusts font size, spacing, or window size

Additional Context (Optional)

No response

Dependency Updates

• Yes, I've updated all my dependencies.