Splitting tables using docx4j

[bhaskar256]

Hi Jason,

We are using docx4j to replace some tags in a docx file with tables. When the number of rows don't fit into one page, we are having the table Header column repeating at the top of each page.

However we have a requirement to Split the table into two separate tables whenever the table goes into a new page and put some text at the top. Something like Table ABC (continued). I can see this is not a table property in MS Word but a separate action performed from the Layout tab.

Is it possible to achieve this using docx4j?

Thanks in advance.

[jason]

Is it possible to achieve this using docx4j?

In principle, yes. In practice, you'll have 2 issues.

Issue 1: take vertically merged cells into account, if splitting on a row affected by them

Issue 2: how to determine when the table spills onto a new page? For this, you need to know where the pages start and end, and for that, you need a page layout model, and presumably one which mimics Word's (unless you only care about PDF output?). docx4j doesn't have a page layout model.

[bhaskar256]

Hi,

Thanks for the prompt reply.

I can see doc4j works basically with the xml representation of the Word document and has no control over such actions.

But are you aware any API I can try to achieve this?

Thanks in advance.

[jason]

Update, September 2026

The blocker in this thread was the second one: docx4j had no page layout model, so it couldn't know which row of a table lands on which page. It has one now, so here is how the "Table ABC (continued)" split looks today.

If the output is a docx

From 17.1.1, org.docx4j.model.pagination.Paginate lays the document out with Apache FOP (docx4j-export-fo on the classpath; since 17.1.0 that layout follows Word's rules, including for tables: row keeps, repeating header rows, rows that can't split) and reports which page every paragraph starts on - and that includes the paragraphs inside table cells:

Code: Select all

PaginationMap map = Paginate.compute(wordMLPackage, null);
// for a row: page of its first cell's first paragraph
int page = map.getPageIndex(paraIdOf(firstParagraphIn(tr)));


So the algorithm is:

1. paginate;
2. walk the table's rows; the first row whose page is later than the table's start page is your split point;
3. cut the w:tbl there: a second w:tbl with a copy of w:tblPr and w:tblGrid, the remaining rows moved into it, and your "Table ABC (continued)" paragraph in between (plus a copy of the header row if you want that too);
4. repeat for the second table, since it may itself span pages.

Two things to be careful of, one of them from my 2013 answer. Vertically merged cells: don't split inside a merge group - if the row at the split point has a cell with w:vMerge (continue), move the split up to the row that started the merge, or the second table begins with a dangling continuation. And the split itself changes the layout (you've added a paragraph, and the second table starts fresh), so paginate again afterwards and check nothing moved; in practice it settles in one extra pass, but the check is cheap.

If the output is a PDF

You may not need to split at all. Mark the header row as a repeating header (w:tblHeader, "Repeat as header row" in Word); docx4j's PDF output honours it on every page the table continues onto. What that doesn't give you is the literal "(continued)" text - that would need XSL-FO's retrieve-table-marker, which docx4j doesn't emit - so if the wording matters, use the docx-side split above and then convert.

Caveat as always: the layout is FOP's, using the fonts FOP can see, so page boundaries are close to Word's rather than identical. For a table split that is usually fine, since Word re-flows whatever you give it and the split row is a sensible place either way.