docx-js/docs/usage/tables.md

Tables

!> Paragraphs requires an understanding of Sections.

Intro

Create a simple table like so:

const table = new Table({
    rows: [Array of `TableRow`s]
});

Then add the table in the section

doc.addSection({
    children: [table],
});

Table Row

A table consists of multiple table rows. Table rows have a list of children which accepts a list of table cells explained below. You can create a simple table row like so:

const tableRow = new TableRow({
    children: [
        new TableCell({
            children: [new Paragraph("hello")],
        }),
    ],
});

Or preferably, add the tableRow directly into the table without declaring a variable:

const table = new Table({
    rows: [
        new TableRow({
            children: [
                new TableCell({
                    children: [new Paragraph("hello")],
                }),
            ],
        }),
    ],
});

Options

Here is a list of options you can add to the table row:

Property	Type	Notes
children	Array<TableCell>	Required
cantSplit	boolean	Optional
tableHeader	boolean	Optional
height	{ value: number, rule: HeightRule }	Optional

Cells

Cells need to be added in the table row, you can create a table cell like:

const tableCell = new TableCell({
    children: [new Paragraph("hello")],
});

Or preferably, add the tableRow directly into the table row without declaring a variable:

const tableRow = new TableRow({
    children: [
        new TableCell({
            children: [new Paragraph("hello")],
        }),
    ],
});

Property	Type	Notes
children	Array<TableCell>	Required
cantSplit	boolean	Optional
tableHeader	boolean	Optional
height	{ value: number, rule: HeightRule }	Optional

Options

readonly shading?: ITableShadingAttributesProperties; readonly margins?: ITableCellMarginOptions; readonly verticalAlign?: VerticalAlign; readonly verticalMerge?: VMergeType; readonly columnSpan?: number; readonly borders?: { readonly top?: { readonly style: BorderStyle; readonly size: number; readonly color: string; }; readonly bottom?: { readonly style: BorderStyle; readonly size: number; readonly color: string; }; readonly left?: { readonly style: BorderStyle; readonly size: number; readonly color: string; }; readonly right?: { readonly style: BorderStyle; readonly size: number; readonly color: string; }; }; readonly children: Array<Paragraph | Table>;

Add paragraph to a cell

Once you have got the cell, you can add data to it with the add() method.

new TableCell({
    children: [new Paragraph("Hello")],
}),

Set width of a cell

You can specify the width of a cell using:

cell.Properties.setWidth(width, format)

format can be:

• WidthType.AUTO
• WidthType.DXA: value is in twentieths of a point
• WidthType.NIL: is considered as zero
• WidthType.PCT: percent of table width

Example

cell.Properties.setWidth(100, WidthType.DXA);

cell.Properties.setWidth("50%", WidthType.PCT);

Borders

BorderStyle can be imported from docx. Size determines the thickness. HTML color can be a hex code or alias such as red.

cell.Borders.addTopBorder([BorderStyle], [SIZE], [HTML COLOR]);

cell.Borders.addBottomBorder([BorderStyle], [SIZE], [HTML COLOR]);

cell.Borders.addStartBorder([[BorderStyle]], [SIZE], [HTML COLOR]);

cell.Borders.addEndBorder([BorderStyle], [SIZE], [HTML COLOR]);

Example

import { BorderStyle } from "docx";

cell.Borders.addStartBorder(BorderStyle.DOT_DOT_DASH, 3, "green");
cell.Borders.addEndBorder(BorderStyle.DOT_DOT_DASH, 3, "#ff8000");

Google DOCS

Google DOCS does not support start and end borders, instead they use left and right borders. So to set left and right borders for Google DOCS you should use:

import { BorderStyle } from "docx";

cell.Borders.addLeftBorder(BorderStyle.DOT_DOT_DASH, 3, "green");
cell.Borders.addRightBorder(BorderStyle.DOT_DOT_DASH, 3, "#ff8000");

Set Width

import { WidthType } from "docx";

table.setWidth([WIDTH], [OPTIONAL WidthType. Defaults to DXA]);

For example:

table.setWidth(4535, WidthType.DXA);

Vertical Align

Sets the vertical alignment of the contents of the cell

import { VerticalAlign } from "docx";

cell.setVerticalAlign([VerticalAlign TYPE]);

For example, to center align a cell:

cell.setVerticalAlign(VerticalAlign.CENTER);

Rows

To get a row, use the getRow method on a table. There are a handful of methods which you can apply to a row which will be explained below.

table.getRow([ROW INDEX]);

Merge cells together

Merging on a row

First obtain the row, and call mergeCells(). The first argument is where the merge should start. The second argument is where the merge should end.

table.getRow(0).mergeCells([FROM INDEX], [TO INDEX]);

Example

This will merge 3 cells together starting from index 0:

table.getRow(0).mergeCells(0, 2);

Merging on a column

It has not been implemented yet, but it will follow a similar structure as merging a row.

Nested Tables

To have a table within a table

cell.add(new Table(1, 1));

Pagination

###Prevent row pagination To prevent breaking contents of a row across multiple pages, call cantSplit():

table.getRow(0).setCantSplit();

###Repeat row If a table is paginated on multiple pages, it is possible to repeat a row at the top of each new page calling setTableHeader():

table.getRow(0).setTableHeader();

Examples

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/4-basic-table.ts

Custom borders

Example showing how to add colourful borders to tables

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/20-table-cell-borders.ts

Adding images

Example showing how to add images to tables

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/24-images-to-table-cell.ts

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/36-image-to-table-cell.ts

Alignment of text in a cell

Example showing how align text in a table cell

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/31-tables.ts

Shading

Example showing merging of columns and rows and shading

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/32-merge-table-cells.ts

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/41-merge-table-cells-2.ts

Merging columns

Example showing merging of columns and rows

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/43-images-to-table-cell-2.ts

Floating tables

Example

Source: https://github.com/dolanmiu/docx/blob/master/demo/34-floating-tables.ts