DOCX Tables

Create Word documents with properly formatted tables using docx npm library. Tables work consistently across Word and Google Docs. Use when creating DOCX files with tables, especially itineraries, schedules, or data tables.

Create Word documents with tables that work everywhere - Word, Google Docs, etc.

⚠️ THE 5 CRITICAL RULES

1. Dual-Width Sizing (MOST CRITICAL)

Set widths in TWO places - on table AND on each cell:

// Table level
new Table({
  width: { size: 9360, type: WidthType.DXA },
  columnWidths: [1872, 7488],
  rows: [...]
})

// Cell level - EVERY cell needs width!
new TableCell({
  width: { size: 1872, type: WidthType.DXA },
  children: [...]
})

2. Use DXA Only, Never Percentages

Percentages break in Google Docs. Use DXA:

• 1 inch = 1440 DXA
• US Letter with 1" margins = 9360 DXA

// ❌ WRONG
width: { size: 100, type: WidthType.PERCENTAGE }

// ✅ CORRECT
width: { size: 9360, type: WidthType.DXA }

3. Use ShadingType.CLEAR

const { ShadingType } = require('docx');

// ❌ WRONG - black background!
shading: { type: ShadingType.SOLID, fill: "E0F2F1" }

// ✅ CORRECT
shading: { type: ShadingType.CLEAR, fill: "E0F2F1" }

4. Add Cell Padding

const cellMargins = { top: 80, bottom: 80, left: 120, right: 120 };

new TableCell({
  margins: cellMargins,
  children: [...]
})

5. Column Widths Must Sum Exactly

For 1" margins: 9360 DXA

columnWidths: [1872, 7488]  // = 9360 ✓
columnWidths: [3120, 3120, 3120]  // = 9360 ✓

Complete Working Example

const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell, 
         WidthType, AlignmentType, BorderStyle, TableLayoutType, ShadingType } = require('docx');
const fs = require('fs');

const TOTAL_WIDTH = 9360;
const COL1 = 1872;
const COL2 = 7488;

const cellBorders = {
  top: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  bottom: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  left: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" },
  right: { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" }
};

const cellMargins = { top: 80, bottom: 80, left: 120, right: 120 };

const doc = new Document({
  sections: [{
    properties: { 
      page: { margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
    },
    children: [
      new Table({
        layout: TableLayoutType.FIXED,
        width: { size: TOTAL_WIDTH, type: WidthType.DXA },
        columnWidths: [COL1, COL2],
        rows: [
          new TableRow({
            children: [
              new TableCell({
                children: [new Paragraph({ 
                  children: [new TextRun({ text: "Header", bold: true, color: "FFFFFF" })],
                  alignment: AlignmentType.CENTER
                })],
                width: { size: TOTAL_WIDTH, type: WidthType.DXA },
                columnSpan: 2,
                shading: { type: ShadingType.CLEAR, fill: "1565C0" },
                borders: cellBorders,
                margins: cellMargins
              })
            ]
          }),
          new TableRow({
            children: [
              new TableCell({
                children: [new Paragraph("Col 1")],
                width: { size: COL1, type: WidthType.DXA },
                borders: cellBorders,
                margins: cellMargins
              }),
              new TableCell({
                children: [new Paragraph("Col 2")],
                width: { size: COL2, type: WidthType.DXA },
                borders: cellBorders,
                margins: cellMargins
              })
            ]
          })
        ]
      })
    ]
  }]
});

Packer.toBuffer(doc).then(buffer => {
  fs.writeFileSync('output.docx', buffer);
});

Column Width Cheat Sheet

For US Letter with 1" margins = 9360 DXA:

Layout	Column Widths
2 cols (20/80)	[1872, 7488]
2 cols (25/75)	[2340, 7020]
2 cols (equal)	[4680, 4680]
3 cols (equal)	[3120, 3120, 3120]
3 cols (25/25/50)	[2340, 2340, 4680]

Troubleshooting

Tables narrow in Google Docs?

• Use WidthType.DXA, not PERCENTAGE
• Add width to EVERY TableCell

Cell backgrounds black?

• Use ShadingType.CLEAR, not SOLID

Text touching borders?

• Add margins: { top: 80, bottom: 80, left: 120, right: 120 }

Columns uneven?

• Verify column widths sum to exactly 9360