WidthType.PERCENTAGE doesn't work for tables in Google Docs or Apple Pages

[jwerre]

When creating the following table using percent widths it works fine in Word but doesn't in Google Docs or Apple Pages:

const fs = require('fs');
const {execSync} = require('child_process');
const {
	Document,
	Packer,
	Paragraph,
	Table,
	TableCell,
	TableRow,
	WidthType
} = require('docx');

const dxaWidthTable = new Table({
	width: {
		size: 100,
		type: WidthType.PERCENTAGE,
	},
	columnWidths: [3505, 5505],
	rows: [
		new TableRow({
			children: [
				new TableCell({
					width: {
						size: 3505,
						type: WidthType.DXA,
					},
					children: [new Paragraph('Hello')],
				}),
				new TableCell({
					width: {
						size: 5505,
						type: WidthType.DXA,
					},
					children: [],
				}),
			],
		}),
		new TableRow({
			children: [
				new TableCell({
					width: {
						size: 3505,
						type: WidthType.DXA,
					},
					children: [],
				}),
				new TableCell({
					width: {
						size: 5505,
						type: WidthType.DXA,
					},
					children: [new Paragraph('World')],
				}),
			],
		}),
	],
});

const percentWidthTable = new Table({
	width: {
		size: 100,
		type: WidthType.PERCENTAGE,
	},
	columnWidths: [90, 10],
	rows: [
		new TableRow({
			children: [
				new TableCell({
					width: {
						size: 90,
						type: WidthType.PERCENTAGE,
					},
					children: [new Paragraph('Hello')],
				}),
				new TableCell({
					width: {
						size: 10,
						type: WidthType.PERCENTAGE,
					},
					children: [],
				}),
			],
		}),
		new TableRow({
			children: [
				new TableCell({
					width: {
						size: 90,
						type: WidthType.PERCENTAGE,
					},
					children: [],
				}),
				new TableCell({
					width: {
						size: 10,
						type: WidthType.PERCENTAGE,
					},
					children: [new Paragraph('World')],
				}),
			],
		}),
	],
});


const doc = new Document({
	sections: [
		{
			children: [
				new Paragraph({ text: 'Table with DXA widths' }),
				dxaWidthTable,
				new Paragraph({ text: 'Table with percentage widths' }),
				percentWidthTable,
			],
		},
	],
});


const fileName = `/tmp/test-${(new Date().getTime()).toString(36)}.docx`;

(async () => {

	const buffer = await Packer.toBuffer(doc);

	fs.writeFileSync(fileName, buffer);
	execSync(`open ${fileName}`);
	execSync(`open -a /Applications/Pages.app ${fileName}`);

})();

The result looks like this:

Node.js: 14.17.5
docx: v 7.3.0

[anti-the-social]

Bonjour :)

Very known issue. Best explanation is in here, I think: #349

[ttieli]

First off, thanks for docx — it's the engine behind a CLI I maintain (ttieli/docxjs-cli) and it's been a joy to build on. Hoping the notes below are useful for this long-standing issue.

This still reproduces on the freshly released docx@9.7.0 (2026-05-24). The impact also turns out to be broader than the title suggests: every Apple OOXML renderer that shares the system parser shows the same collapsed-table behaviour — QuickLook in Finder, Pages, Mail.app attachment preview, iCloud online preview, Spotlight thumbnails, and Quick Look on iOS / iPadOS Files. Microsoft Word and WPS render the same file fine because they're more lenient.

What I observed in 9.7.0 source

Two things compose together, and either alone is recoverable; together they explain the strict-parser collapse.

1. WidthType.PERCENTAGE writes a literal "%" string — dist/index.cjs:20177:

if (type === WidthType.PERCENTAGE && typeof size === "number")
    tableWidthValue = `${size}%`;

The ECMA-376 schema (§17.18.87 ST_TblWidth + §22.9.2.6 ST_MeasurementOrPercent) defines w:w under w:type="pct" as a plain integer in fiftieths of a percent — so 100% is 5000, not "100%". Strict parsers don't accept the string form and silently fall back to tblGrid. The library's own JSDoc in src/file/table/table-width.ts:67 already documents the intent as { size: 50, type: PERCENTAGE } meaning 50%, so the semantic isn't in question, just the wire format.

2. Table.columnWidths defaults to Array(N).fill(100) twips — dist/index.cjs:21093. At ~1.76 mm per column that's narrower than a single CJK character, so once tblW is ignored the fallback width is unreadable. @fpirsch nailed this exact behavior back in #349 (2019), and that diagnosis still holds.

A non-breaking fix for the first part

The first one looks like it could be a one-line change:

- if (type === WidthType.PERCENTAGE && typeof size === "number") {
-     tableWidthValue = `${size}%`;
- }
+ if (type === WidthType.PERCENTAGE && typeof size === "number") {
+     // OOXML: pct type takes a 1/50-of-a-percent integer (100% = 5000).
+     // The literal "${size}%" form was not accepted by strict OOXML
+     // renderers (Apple QuickLook / Pages / Mail / iCloud / Spotlight,
+     // Google Docs).
+     tableWidthValue = Math.round(size * 50);
+ }

What the rendered output looks like before and after:

User input	Before (w:w)	After (w:w)	Word	Pages / QuickLook / Google Docs
size: 100	"100%"	5000	100% (unchanged)	collapsed → 100%
size: 50	"50%"	2500	50% (unchanged)	collapsed → 50%

The percentage rendered in every reader stays the same; only the wire format becomes spec-conformant. The only thing that could observably change is downstream code that greps the XML for the literal "100%" string, which I'd expect to be rare.

Affected files would be:

• src/file/table/table-width.ts — the diff above
• src/file/table/table.spec.ts:284 — update the assertion from "w:w": "100%" to "w:w": 5000
• src/file/table/table.spec.ts — add a positive case for { size: 50, type: PERCENTAGE } → w:w === 2500

I left the columnWidths default alone deliberately — changing the default value feels more like a design discussion than a bugfix, since any change there is observably different for consumers who rely on the current behavior.

Downstream workaround (in case it helps anyone landing here)

For now I worked around it in my project by switching the three table call sites from WidthType.PERCENTAGE to WidthType.DXA with explicitly computed columnWidths and layout: TableLayoutType.FIXED. Works, but obviously it'd be nicer to use PERCENTAGE directly.

@dolanmiu — if you'd be open to a PR along the lines above I'd be happy to put one together. Totally understand if you'd rather think about it differently or leave it for now; just wanted to share what I found in case it's useful.

[ttieli]

嘿 @dolanmiu — 给上面那条偏技术的评论补一句私人的话。

我真的很喜欢你的 docx 库，它撑着我自己的一个小工具跑了好一阵子，谢谢你这些年坚持维护。坦白说：上面那条评论里的源码定位、ECMA-376 引用、diff 表格是我和 Claude 一起调研整理出来的——但坐在键盘前的是个活人，不是机器人在批量灌水 issue。会花时间写那么细，是因为这个 bug 卡了 4 年挺可惜的，想把根因和最小修复路径放在一个地方让你判断起来轻松点，不是给你压力。

如果 PR 思路你想到任何地方需要改，或者觉得现在不是时候改这个，都直接说就行——我不介意。如果你愿意离开 issue 走邮件之类的私下聊聊，告诉我哪里方便就行。

再次谢谢你做的库。

—— Tieli (ttieli)

---

English translation:

Hey @dolanmiu — a quick personal note on top of the technical comment above.

I genuinely love docx; it's been holding up a small tool of mine for a good while, and I appreciate the years you've put into maintaining it. To be fully transparent: the source pointers, ECMA-376 references, and diff table above were researched and drafted with Claude as a coding assistant — but there's a real person at the keyboard, not a bot mass-spamming issues. I took the time to write it out in detail because this issue has been sitting open for four years and I wanted to put the root cause and minimal fix in one place so it's low-effort for you to evaluate, not to put pressure on you.

If you'd like to adjust the PR approach in any way, or you don't feel this is the right time to touch it, just say so — totally fine either way. If you'd ever prefer to take the conversation off-thread (email or wherever), just let me know what's easiest.

Thanks again for the library.

—— Tieli (ttieli)