Google docs - like pagination

[scape76]

I want to implement a plugin into the editor which purpose is to emulate the content into an A4 page format, and automatically split the content for the user when the max height is exceeded.

As far as I know, platejs has no extensions that allow the editor to enter to this "page" format. It's pageless

Use Case
Many apps with more conventional users (mainly in industries such as lawyers, legal guardians, any anyone which has to work with lots of paper) still need online editors that emulate the content into an A4 page format. Many need to print it out or export it to PDF to be sent to recipients that need to document in A4 format.

Would love to hear ideas on how to potentially implement this extension
My first thought is to keep editor's top level children to be nodes that represent pages
if content goes out of page's height, create a new page below and move the content there

[dosubot[bot]]

There isn’t a built-in pagination or A4 page format plugin in Plate, but the plugin system is flexible enough to support this. You can introduce a custom top-level "page" node (similar to how tables are implemented) and use normalization to ensure all content is wrapped inside these page nodes. When a page’s rendered height exceeds your A4 limit, you’d programmatically move overflowing content into a new page node below.

Plate’s architecture supports custom node structures and normalization, so you can manage splitting, merging, and rendering pages using the same patterns as the table plugin. You’ll need to handle edge cases like orphan paragraphs and editing across page boundaries, but the hooks and rendering components (PlateStatic, ElementStatic, etc.) are designed for this kind of extensibility. See examples of custom node and normalization logic in the table plugin for inspiration example.

If you want to discuss implementation details or edge cases, let me know!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[skynth]

An extension here would be fantastic

[scape76]

@skynth I've got a really basic extension done that works for me. It's not really well-designed, but at least something to start off.

here is the plugin:

import type { PluginConfig } from "platejs"

import { createTSlatePlugin } from "platejs"

import { DOCUMENT_DEFAULTS, INCHES_TO_CM, PPI } from "./constants"
import { normalizeInitialValuePagination } from "./normalizeInitialValuePagination"
import { withPagination } from "./withPagination"

export type PaginationConfig = PluginConfig<
  "pagination",
  {
    documentSettings: {
      type: "A4"
      sizes: {
        width: number
        height: number
      }
      margins: {
        top: number
        bottom: number
        left: number
        right: number
      }
    }
  },
  {
    create: {}
  },
  {
    insert: {}
  },
  {}
>

export const BasePaginationPlugin = createTSlatePlugin<PaginationConfig>({
  key: "pagination",
  node: {
    isElement: true,
    isContainer: true,
    isSelectable: false,
    isInline: true,
    type: "page",
  },
  options: {
    documentSettings: {
      type: "A4",
      sizes: DOCUMENT_DEFAULTS.A4.sizes,
      margins: DOCUMENT_DEFAULTS.A4.margins,
    },
  },
  normalizeInitialValue: normalizeInitialValuePagination,
})
  .extendSelectors(({ getOption }) => ({
    sizes: () => getOption("documentSettings").sizes,
    sizesCm: () => {
      const base = getOption("documentSettings").sizes

      return {
        width: INCHES_TO_CM(base.width / PPI),
        height: INCHES_TO_CM(base.height / PPI),
      }
    },
    margins: () => getOption("documentSettings").margins,
    marginsCm: () => {
      const base = getOption("documentSettings").margins

      return {
        top: INCHES_TO_CM(base.top / PPI),
        bottom: INCHES_TO_CM(base.bottom / PPI),
        left: INCHES_TO_CM(base.left / PPI),
        right: INCHES_TO_CM(base.right / PPI),
      }
    },
  }))
  .overrideEditor(withPagination)

import type { PaginationConfig } from "./BasePaginationPlugin"

import { ElementApi } from "platejs"
import { OverrideEditor } from "platejs/react"

export const withPagination: OverrideEditor<PaginationConfig> = ({
  editor,
  tf: { normalizeNode },
  type,
}) => ({
  transforms: {
    normalizeNode([n, path]) {
      if (ElementApi.isElement(n)) {
        if (n.type === type) {
          if (path.length > 1) {
            editor.tf.unwrapNodes({
              at: path,
            })
          }
        }
      }

      normalizeNode([n, path])
    },
  },
})

import type { NodeEntry, NormalizeInitialValue, TElement, TText } from "platejs"
import type { PaginationConfig } from "./BasePaginationPlugin"

export const normalizeInitialValuePagination: NormalizeInitialValue<
  PaginationConfig
> = ({ editor }) => {
  // to normalize initial value:
  // first step:
  // check that all root nodes are pages
  // if they are not, grab them all from top to bottom and move them in a page container
  // returns true if normalization needs to continue
  // returns false if normalization is done
  const normalizeRootNodes = () => {
    const rootNodesGen = editor.api.nodes({
      at: [],
      match: (_, path) => path.length === 1,
      mode: "highest",
    })

    let batch: NodeEntry<TElement | TText>[] = []
    let current = rootNodesGen.next()

    const moveBatchNodesToPage = () => {
      const firstBatchPath = batch[0][1]
      const lastBatchPath = batch[batch.length - 1][1]

      editor.tf.withoutNormalizing(() => {
        editor.tf.wrapNodes(
          {
            type: "page",
            children: [],
          },
          {
            at: [],
            match: (_, path) => {
              if (path.length !== 1) return false
              return path[0] >= firstBatchPath[0] && path[0] <= lastBatchPath[0]
            },
            mode: "highest",
          },
        )
      })
    }

    while (current.value) {
      const elem = current.value[0]
      if (elem.type !== "page") {
        batch.push(current.value)
      }

      if (elem.type === "page") {
        if (batch.length > 0) {
          moveBatchNodesToPage()
          return true
        }
      }

      current = rootNodesGen.next()
    }

    if (batch.length > 0) {
      moveBatchNodesToPage()
      return true
    }

    return false
  }

  while (normalizeRootNodes()) {}

  // second step:
  // on this step we know that every root node is a page
  // going from top page (0-indexed) to bottom:
  // if content overflows (for now, lets say that its 20+ children),
  // push it to bottom page
  /**
   * @argument {number} path - current's page path that requires normalization
   * @returns {number} index of next page that needs to be normalized. -1 if not needed
   */
  // this step doesnt work as needed. for that to work correctly,
  // I need to calculate real height of elements on this step, but it can only be done
  // using shadow rendering or 'at the moment' as it done in @/components/ui/page-element.tsx
  // function normalizeOverflow(path: Path): Path | false {
  //   const node = editor.api.node(path)

  //   console.log("current page is ", node)

  //   if (!node) return false

  //   const nodesGen = editor.api.nodes({
  //     at: path,
  //     match: (_, path) => path.length === 2,
  //     mode: "highest",
  //   })

  //   const nodes = Array.from(nodesGen)
  //   console.log("nodes count is ", nodes.length)
  //   const nextPagePath = PathApi.next(path)
  //   console.log("next page path ", nextPagePath)

  //   // the *rule* that identifies if the content on the page overflows
  //   const maxItemsPerPage = 30
  //   if (nodes.length > maxItemsPerPage) {
  //     editor.tf.withoutNormalizing(() => {
  //       editor.tf.wrapNodes(
  //         {
  //           type: "page",
  //           children: [],
  //         },
  //         {
  //           at: path,
  //           match: (_, p) => p[p.length - 1] > maxItemsPerPage - 1,
  //         },
  //       )

  //       editor.tf.moveNodes({
  //         at: [...path, maxItemsPerPage],
  //         to: nextPagePath,
  //       })
  //     })
  //   }

  //   return nextPagePath
  // }

  // let nextPath = normalizeOverflow([0])

  // while (nextPath) {
  //   nextPath = normalizeOverflow(nextPath)
  // }
}

I wasnt able to make elements move from page to page just by using normalization. For that, you need to know the size of each element within the page node. I had two options on how could I implement this:

1. estimate sizes for each of the node element
2. do shadow rendering and get the real sizes

with first option I had no success as paragraph nodes can wrap, and at which point they will wrap was kind of hard to estimate by just having the text
the second option was not really performant as its the same as rendering each editor's children twice

Yet I needed the auto-moving between pages so I've decided to do it in a hacky and really bad way:

import { useEffect, useRef } from "react"

import { PlateElementProps, useEditorRef, usePluginOption } from "platejs/react"

import { useMounted } from "@/shared/hooks/use-mounted"

import { PaginationPlugin } from "../editor/plugins/pagination/react"

export function PageElement(props: PlateElementProps) {
  const sizes = usePluginOption(PaginationPlugin, "sizes")
  const margins = usePluginOption(PaginationPlugin, "margins")
  const containerRef = useOverflowDetection(props)

  return (
    <div
      ref={containerRef}
      className="relative outline outline-1 outline-neutral-400"
      style={{
        width: `${sizes.width}px`,
        height: `${sizes.height}px`,
        paddingTop: margins.top ? `${margins.top}px` : undefined,
        paddingBottom: margins.bottom ? `${margins.bottom}px` : undefined,
        paddingLeft: margins.left ? `${margins.left}px` : undefined,
        paddingRight: margins.right ? `${margins.right}px` : undefined,
      }}
    >
      {props.children}
    </div>
  )
}

function useOverflowDetection(props: PlateElementProps) {
  const mounted = useMounted()
  const editor = useEditorRef()
  const currentPath = props.path

  const containerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    const container = containerRef.current

    if (!mounted || !container || !currentPath || !editor.api.node({ at: [] }))
      return

    const nextPagePath = [currentPath[0] + 1]

    if (container.scrollHeight > container.clientHeight) {
      editor.tf.withoutNormalizing(() => {
        const nextPage = editor.api.node(nextPagePath)

        if (!nextPage) {
          editor.tf.wrapNodes(
            {
              type: "page",
              children: [],
            },
            {
              at: currentPath.concat([container.children.length - 1]),
            },
          )

          editor.tf.moveNodes({
            at: currentPath.concat([container.children.length - 1]),
            to: nextPagePath,
          })
        } else {
          const node1 = editor.api.node(
            currentPath.concat([container.children.length - 1]),
          )
          const node2 = editor.api.node(nextPagePath.concat([0]))

          if (!node1 || !node2 || !node1[0] || !node2[0]) return

          editor.tf.moveNodes({
            at: currentPath.concat([container.children.length - 1]),
            to: nextPagePath.concat([0]),
            mode: "highest",
          })
        }
      })
    }
  }, [containerRef?.current?.scrollHeight])

  return containerRef
}

as you see the page node itself is responsible for this logic. Im really sure its possible to dig into two previous options I considered and find a better success with it.
I also wonder how google handles it? Probably they have their own render engine with which they can calculate size of each node and decide should it be moved to another page or not?

Also would be really cool to hear some minds behind platejs, how can I make a better extension and what to consider @zbeyens @felixfeng33

[felixfeng33]

It sounds different from #4007, as it still loads all the nodes at once, but it's still a good plugin.
We have a useHooks plugin option, perhaps we can wait until the editor has fully loaded, then retrieve each block's node and calculate its size then insert something like hr use this to implement pagination?

[felixfeng33]

@claude can you help?

[zbeyens]

I did a paging plugin in the past, unfortunately I won't have free time to open-source it. Here is a quick analysis from AI.

---

Core Architecture

The plugin wraps all content inside page nodes, using normalization to ensure
proper page structure. Each page acts as a container with calculated dimensions
based on A4 paper size (8.5" × 11" with 1" margins).

Normalization Strategy

The normalization system enforces several rules:

1. Wrap blocks not in pages - All top-level content must be inside page nodes
2. Prevent nested pages - Pages cannot contain other pages
3. Handle empty pages - Remove pages with no content
4. Page overflow - Move overflowing content to the next page
5. Soft split/merge - Handle elements spanning multiple pages

Soft Split/Merge Implementation

This is the most complex feature - elements (especially tables) can span across
page boundaries:

• Soft Split: When a table exceeds page height, it's split into multiple tables
• Property Sync: Styling, alignment, indentation are synchronized across split parts
• Cell-level granularity: Tables can split mid-row, with partial rows on different pages
• Soft Merge: When there's room, split elements merge back together

Edge Cases Handled

1. Table splitting within rows - Can move individual cells to the next page
2. Orphan prevention - Single paragraphs at page boundaries
3. Header/footer preservation - Maintains consistent headers across pages
4. Footnote handling - Special spacing calculations for footnotes
5. Style synchronization - Ensures split elements maintain consistent formatting
6. Bidirectional flow - Content can move both forward and backward between pages

Performance Issue: DOM Measuring

The major performance bottleneck is DOM measuring being too slow, especially for real-time page breaks:

1. Word-by-word measurement - Calculates precise layout
   by measuring every word
2. No caching - Measurements are recalculated on every normalization pass
3. Recursive measurements - Tables and nested blocks trigger cascading DOM reads
4. Real-time calculation - All measurements are synchronous and blocking

This approach, while accurate, is too computationally expensive for smooth
real-time editing, especially with complex documents containing tables, images,
and nested structures.

Canvas-Based Text Measurement

Your implementation uses a clever approach with the typometer module:

1. Canvas Context Reuse:

   • Creates a single 1x1 canvas element
   • Reuses the same 2D context for all measurements
   • Uses context.measureText() which is much faster than DOM measurements

2. Word Width Caching:

   • Caches measurements in editor.page.wordWidths keyed by word ID
   • Only measures each unique word/style combination once
   • Subsequent lookups are O(1) hash table lookups

3. Performance Benefits:

   • Canvas measurements are ~10-100x faster than DOM measurements
   • No DOM reflows or style recalculations
   • Synchronous API without layout thrashing
   • Memory-efficient with the small canvas

However, even with Canvas measuring, the performance bottleneck remains for
real-time page breaks because:

1. Volume of calculations: Still processing word-by-word for entire documents
2. Complex layout logic: Tables, nested blocks, and soft splits require
   extensive calculations
3. Normalization frequency: Every edit triggers page reflow calculations
4. No debouncing: Real-time updates on every keystroke

Architectural Solution: Virtual Pages

A more scalable approach would involve rewriting slate-react to support virtual
pages without container nodes in the document structure. Instead of wrapping
content in page nodes and using complex normalization, pages would be rendered
as a visual layer on top of the natural document flow.

This would eliminate several performance bottlenecks:

1. No normalization overhead: Content wouldn't need to be moved between page
   containers
2. Simpler data model: The document structure remains flat and natural
3. Cleaner operations: No need to handle soft splits/merges in the data layer
4. Better performance: Page calculations could happen asynchronously without
   blocking editing

The virtual page system would track element positions and render page
boundaries visually, while keeping the underlying Slate document structure
unchanged. This separation of concerns - data vs. presentation - would make the
editor more maintainable and performant, especially for large documents.