> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tables

## `Table`

A live handle to one top-level or cell-nested w:tbl element.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### Table properties

| Name | Type | Description |
| - | - | - |
| `alignment` | `Alignment` | Placement of the table against the page column. |
| `cellSpacing` | `number` | Extension (VBA `Table.Spacing`, Office.js `TableStyle.cellSpacing`): points of space between cells, the direct `w:tblCellSpacing`; 0 removes it. |
| `columnCount` | `number` | read-only |
| `columns` | `HandleCollection<TableColumn>` | read-only |
| `description` | `string` | office.js Table.description: `w:tblPr/w:tblDescription`, the alt text of the table. |
| `endnotes` | `HandleCollection<NoteItem>` | read-only office.js Table.endnotes: the endnotes referenced from inside the table. |
| `fields` | `FieldCollection` | read-only office.js Table.fields: every field the table's paragraphs hold, nested tables included. |
| `font` | `Font` | read-only Run formatting over every cell's text. |
| `footnotes` | `HandleCollection<NoteItem>` | read-only office.js Table.footnotes: the footnotes referenced from inside the table. |
| `headerRowCount` | `number` | Number of consecutive header rows from the top of the table. |
| `horizontalAlignment` | `Alignment` | Direct paragraph alignment shared by every cell, or Mixed when it differs. |
| `isUniform` | `boolean` | read-only True when every physical row contains the same number of cells. |
| `nestingLevel` | `number` | read-only Top-level tables are level 1; each containing table adds one. |
| `parentBody` | `Body` | read-only |
| `parentContentControl` | `ContentControl` | read-only office.js Table.parentContentControl: the nearest w:sdt ancestor of the w:tbl. |
| `parentContentControlOrNullObject` | `ContentControl` | read-only |
| `parentTable` | `Table` | read-only |
| `parentTableCell` | `TableCell` | read-only |
| `parentTableCellOrNullObject` | `TableCell & { isNullObject: boolean }` | read-only |
| `parentTableOrNullObject` | `Table & { isNullObject: boolean }` | read-only |
| `rowCount` | `number` | read-only |
| `rows` | `TableRowCollection<TableRow>` | read-only |
| `shading` | `ShadingUniversal` | read-only |
| `shadingColor` | `string` | |
| `style` | `string \| undefined` | The table's style name: its direct w:tblStyle, or the document default table style. Accepts a style name, style ID, or OfficeJS BuiltInStyleName spelling on write; a Word built-in the document never defined (e.g. "Table Grid") is injected with its factory definition. |
| `styleBandedColumns` | `boolean` | |
| `styleBandedRows` | `boolean` | |
| `styleBuiltIn` | `string \| undefined` | OfficeJS spelling: reads the Word built-in name ("TableGrid" even when the document's ID is localized), falling back to the raw style ID for custom styles; writes like `style`. |
| `styleFirstColumn` | `boolean` | |
| `styleFirstRow` | `boolean` | The w:tblLook firstRow flag: whether the table style's FirstRow condition paints. |
| `styleLastColumn` | `boolean` | |
| `styleTotalRow` | `boolean` | |
| `tableDirection` | `TableDirection` | The table's visual direction (`w:bidiVisual`): "RightToLeft" mirrors the grid, so logical column 0 paints at the right edge and cell handles keep their logical indices. Reads the effective value — direct property, else the table style chain — and writes an explicit direct property, so "LeftToRight" overrides an RTL table style. Null clears the direct property, so the style value shows through again. |
| `tables` | `TableCollection<Table>` | read-only |
| `title` | `string` | office.js Table.title: `w:tblPr/w:tblCaption`, the caption Word's accessibility pane reads. |
| `values` | `string[][]` | Cell text row by row, one entry per physical cell as Word reports it: a merged span is one entry, and a cell a vertical merge covers is left out. |
| `verticalAlignment` | `"Mixed" \| "Top" \| "Bottom" \| "Center"` | Direct vertical alignment shared by every physical cell. |
| `width` | `number` | Sum of the logical grid-column widths, in points. |

### `Table.addColumns()`

```ts theme={null}
addColumns(
  location: "Start" | "End",
  columnCount: number,
  values?: string[][],
  options?: { widthPt?: number } & RunFormat,
): void
```

Add columns; `values` is row-major (`values[row][addedColumn]`).

### `Table.addRows()`

```ts theme={null}
addRows(
  location: RowInsertLocation,
  rowCount: number,
  values?: string[][],
  format?: RunFormat,
): TableRowCollection<TableRow>
```

Add rows cloned from the adjacent row's formatting; returns the new rows.
`values` is row-major with `rowCount` rows sized to the adjacent row's
`cells` (vertical-merge continuations, which become ordinary empty cells
in the clone, may be included or omitted).

### `Table.autoFitBehavior()`

```ts theme={null}
autoFitBehavior(behavior: "Content" | "FixedSize" | "Window"): void
```

Word's AutoFit behavior. "FixedSize" freezes the current grid (cell width
writes become authoritative), "Content" reflows columns to their contents,
"Window" stretches the table across the text column.

### `Table.autoFitWindow()`

```ts theme={null}
autoFitWindow(): void
```

Autofit the table to the width of the text column (autoFitBehavior("Window")).

### `Table.clear()`

```ts theme={null}
clear(): void
```

Clear every physical cell's contents without changing the table structure or formatting.

### `Table.convertToText()`

```ts theme={null}
convertToText(
  options?: TableConvertToTextOptions,
  selectedRows?: readonly { element: object }[],
): Range
```

Convert the complete table to paragraph text and return its first range.

### `Table.delete()`

```ts theme={null}
delete(): void
```

### `Table.deleteColumns()`

```ts theme={null}
deleteColumns(columnIndex: number, columnCount?: number): void
```

Delete logical grid columns; spanning cells shrink around them. Word does not track this, even under change tracking.

### `Table.deleteRows()`

```ts theme={null}
deleteRows(rowIndex: number, count?: number): void
```

Delete `count` rows starting at `rowIndex` (the OfficeJS Table.deleteRows shape).

### `Table.distributeColumns()`

```ts theme={null}
distributeColumns(): void
```

Equalize a uniform table's logical columns while preserving total width.
Under tracking the old grid and cell widths are recorded, Word's shape for
a tracked column resize.

### `Table.format()`

```ts theme={null}
format(format: TableFormat): void
```

Direct table sizing, placement, and layout behavior; tracked as property records.

### `Table.getBorder()`

```ts theme={null}
getBorder(location: BorderLocation): TableBorder
```

The table's border at one location, Word's meaning: Top/Bottom/Left/Right
are the OUTER EDGES (the sides of the cells on that boundary), the Inside
locations the shared edges between neighbouring cells. Reads are effective —
direct `w:tcBorders`, else the table's `w:tblBorders`, else the table style
chain — and report Mixed when the covered sides disagree. Writes stay direct
on each covered cell. Conditional `w:tblStylePr` formats are not consulted.

### `Table.getCell()`

```ts theme={null}
getCell(row: number, col: number): TableCell
```

### `Table.getCellByOrdinal()`

```ts theme={null}
getCellByOrdinal(row: number, ordinal: number): TableCell
```

Address by a row's physical cells, the counting OfficeJS getCell uses.

### `Table.getCellOrNullObject()`

```ts theme={null}
getCellOrNullObject(row: number, col: number): TableCell & { isNullObject: boolean }
```

### `Table.getCellPadding()`

```ts theme={null}
getCellPadding(location: CellPaddingLocation): ClientResult<number>
```

### `Table.getNext()`

```ts theme={null}
getNext(): Table
```

The next table in the same body, skipping intervening paragraphs.

### `Table.getNextOrNullObject()`

```ts theme={null}
getNextOrNullObject(): Table & { isNullObject: boolean }
```

### `Table.getOoxml()`

```ts theme={null}
getOoxml(): ClientResult<string>
```

This table's own `w:tbl` element, serialized with the prefixes it uses.
Immediate `ClientResult`; `.value` is the fragment. Use it to read what the
table declares itself, apart from what the table style contributes.

### `Table.getParagraphAfter()`

```ts theme={null}
getParagraphAfter(): Paragraph
```

### `Table.getParagraphAfterOrNullObject()`

```ts theme={null}
getParagraphAfterOrNullObject(): Paragraph & { isNullObject: boolean }
```

### `Table.getParagraphBefore()`

```ts theme={null}
getParagraphBefore(): Paragraph
```

### `Table.getParagraphBeforeOrNullObject()`

```ts theme={null}
getParagraphBeforeOrNullObject(): Paragraph & { isNullObject: boolean }
```

### `Table.getRange()`

```ts theme={null}
getRange(location?: "Start" | "End" | "Before" | "After" | "Whole"): Range
```

### `Table.insertContentControl()`

```ts theme={null}
insertContentControl(type?: ContentControlType): ContentControl
```

office.js Table.insertContentControl: wrap the w:tbl, keeping every handle live.

### `Table.insertParagraph()`

```ts theme={null}
insertParagraph(
  text: string,
  location: "Before" | "After",
  options?: Omit<OfficeRunFormat<InsertParagraphOptions>, "text">,
): Paragraph
```

### `Table.insertTable()`

```ts theme={null}
insertTable(
  rowCount: number,
  columnCount: number,
  location: "Before" | "After",
  values?: string[][],
  options?: TableInsertOptions,
): Table
```

A table directly before or after this one; Word draws the two as one grid.

### `Table.mergeCells()`

```ts theme={null}
mergeCells(
  startRow: number,
  startCol: number,
  endRow: number,
  endCol: number,
): TableCell
```

Merge the rectangle (startRow, startCol)..(endRow, endCol); returns the merged cell.

### `Table.search()`

```ts theme={null}
search(needle: string, options?: SearchOptions): RangeCollection<Range>
```

Literal search over visible cell paragraphs in row-major order.

### `Table.set()`

```ts theme={null}
set(properties: TableUpdateData, options?: UpdateOptions): void
```

### `Table.setCellPadding()`

```ts theme={null}
setCellPadding(location: CellPaddingLocation, padding: number): void
```

### `Table.sort()`

```ts theme={null}
sort(options?: TableSortOptions): void
```

office.js Table.sort: whole rows by up to three columns; excludeHeader keeps the first row.

**Not implemented.** These Office.js members throw: `applyStyleDirectFormatting`, `autoFormat`, `reapplyAutoFormat`, `select`.

## `TableRow`

A live handle to one w:tr element.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### TableRow properties

| Name | Type | Description |
| - | - | - |
| `cellCount` | `number` | read-only Number of navigable cells in this row; merged continuations are excluded. |
| `cells` | `TableCellCollection<TableCell>` | read-only Physical cells at their grid positions; merge continuations are skipped. |
| `endnotes` | `HandleCollection<NoteItem>` | read-only office.js TableRow\.endnotes: the endnotes referenced from inside this row. |
| `fields` | `FieldCollection` | read-only office.js TableRow\.fields: every field in this row's paragraphs, nested tables included. |
| `font` | `Font` | read-only Run formatting over every cell's text in this row. |
| `footnotes` | `HandleCollection<NoteItem>` | read-only office.js TableRow\.footnotes: the footnotes referenced from inside this row. |
| `gridAfter` | `number` | Extension: grid columns left empty after the last cell (w:gridAfter); setting it moves the cells. |
| `gridBefore` | `number` | Extension: grid columns left empty before the first cell (w:gridBefore); setting it moves the cells. |
| `height` | `number` | VBA Row\.Height spelling of preferredHeight; 0 reports no direct height. |
| `heightRule` | `RowHeightRule` | How the direct row height binds; Auto when the row has no usable direct height. |
| `horizontalAlignment` | `Alignment` | Direct paragraph alignment shared by every physical cell, or Mixed. |
| `isHeader` | `boolean` | read-only Whether this row carries the repeat-as-header marker. |
| `parentTable` | `Table` | read-only |
| `preferredHeight` | `number` | Direct preferred row height in points; zero means automatic/no direct height. |
| `range` | `Range` | read-only A live range spanning every paragraph owned by this row's cells. |
| `rowIndex` | `number` | read-only |
| `shading` | `ShadingUniversal` | read-only |
| `shadingColor` | `string` | Direct cell fill shared by the row; empty string represents absent or mixed shading. |
| `values` | `string[][]` | Cell text in grid coordinates: `values[col] === table.getCell(rowIndex, col).value`. |
| `verticalAlignment` | `"Mixed" \| "Top" \| "Bottom" \| "Center"` | Direct vertical alignment shared by every physical cell, or Mixed. |

### `TableRow.clear()`

```ts theme={null}
clear(): void
```

Clear every physical cell, including vertical-merge continuation storage.

### `TableRow.convertToText()`

```ts theme={null}
convertToText(options?: TableConvertToTextOptions): Range
```

### `TableRow.delete()`

```ts theme={null}
delete(): void
```

### `TableRow.format()`

```ts theme={null}
format(format: TableRowFormat): void
```

Repeat-as-header, split behavior, and row height.

### `TableRow.getBorder()`

```ts theme={null}
getBorder(location: BorderLocation): TableBorder
```

### `TableRow.getCellPadding()`

```ts theme={null}
getCellPadding(location: CellPaddingLocation): ClientResult<number>
```

### `TableRow.getNext()`

```ts theme={null}
getNext(): TableRow
```

### `TableRow.getNextOrNullObject()`

```ts theme={null}
getNextOrNullObject(): TableRow & { isNullObject: boolean }
```

### `TableRow.insertContentControl()`

```ts theme={null}
insertContentControl(type?: ContentControlType): ContentControl
```

office.js TableRow\.insertContentControl: wrap the w:tr, keeping every handle live.

### `TableRow.insertRows()`

```ts theme={null}
insertRows(
  location: "Before" | "After",
  rowCount: number,
  values?: string[][],
  format?: RunFormat,
): TableRowCollection<TableRow>
```

Insert rows cloned from this row's shape directly before or after it —
the escape hatch when the table's last row is a merged footer. `values`
rows are sized to this row's `cells` (vertical-merge continuations, which
become ordinary empty cells in the clone, may be included or omitted).

### `TableRow.merge()`

```ts theme={null}
merge(): TableCell
```

Merge every physical cell in this row into one cell.

### `TableRow.search()`

```ts theme={null}
search(needle: string, options?: SearchOptions): RangeCollection<Range>
```

### `TableRow.set()`

```ts theme={null}
set(properties: TableRowUpdateData, options?: UpdateOptions): void
```

### `TableRow.setCellPadding()`

```ts theme={null}
setCellPadding(location: CellPaddingLocation, padding: number): void
```

### `TableRow.setHeight()`

```ts theme={null}
setHeight(rowHeight: number, heightRule: RowHeightRule): void
```

Set the row height using OfficeJS RowHeightRule spellings.

### `TableRow.setLeftIndent()`

```ts theme={null}
setLeftIndent(leftIndent: number, rulerStyle: RulerStyle): void
```

**Not implemented.** These Office.js members throw: `select`.

## `TableCell`

A live handle to one w:tc element.

Import from `@reductoai/docx/node`, `@reductoai/docx/officejs`.

### TableCell properties

| Name | Type | Description |
| - | - | - |
| `body` | `Body` | read-only The cell's content as a body scope (the OfficeJS TableCell.body shape). |
| `cellIndex` | `number` | read-only The cell's logical grid column. |
| `cellOrdinal` | `number` | read-only The cell's ordinal among its row's physical cells: what OfficeJS calls cellIndex. |
| `column` | `TableColumn` | read-only Logical table column that begins at this cell's grid position. |
| `columnSpan` | `number` | read-only Grid columns this cell covers (w:gridSpan). `table.values` repeats a span's text across every covered position, so this is how two writes avoid silently landing in the same physical cell. |
| `columnWidth` | `number` | Width of the logical grid column containing this cell, in points. |
| `edges` | `CellEdges` | read-only Which of this cell's sides lie on the table's outer boundary (vertical merges included). |
| `font` | `Font` | read-only Run formatting over every paragraph the cell owns. |
| `horizontalAlignment` | `Alignment` | Direct paragraph alignment shared by the cell, or Mixed when paragraphs differ. |
| `paragraphs` | `ParagraphCollection<Paragraph>` | read-only |
| `parentRow` | `TableRow` | read-only |
| `parentTable` | `Table` | read-only |
| `rowIndex` | `number` | read-only |
| `rowSpan` | `number` | read-only Grid rows this cell covers (its vertical-merge continuations below). |
| `shading` | `ShadingUniversal` | read-only |
| `shadingColor` | `string` | Effective cell fill: direct, else the table and its style; empty string is no color. |
| `value` | `string` | The cell's text; multiple paragraphs join with "\n". |
| `verticalAlignment` | `"Top" \| "Bottom" \| "Center"` | Effective vertical alignment: direct, else the table style's; absent/top is Top. |
| `width` | `number` | read-only Sum of the grid columns covered by this cell, in points. |

### `TableCell.autoSum()`

```ts theme={null}
autoSum(): void
```

Insert Word's automatic =SUM field, preferring numeric cells above, then to the left.

### `TableCell.delete()`

```ts theme={null}
delete(shiftCells?: DeleteCells): void
```

Delete this cell using Word's cell-shift policy; ShiftLeft is the default.

### `TableCell.deleteColumn()`

```ts theme={null}
deleteColumn(): void
```

### `TableCell.deleteRow()`

```ts theme={null}
deleteRow(): void
```

### `TableCell.fill()`

```ts theme={null}
fill(
  text: string,
  options?: Omit<OfficeRunFormat<InsertParagraphOptions>, "text">,
): Paragraph
```

Fill an answer slot: reuse the cell's trailing blank paragraph when one
exists, otherwise append a new paragraph. Returns the paragraph written.

### `TableCell.format()`

```ts theme={null}
format(format: TableCellFormat): void
```

Shading, vertical alignment, borders, margins, text direction.

### `TableCell.formula()`

```ts theme={null}
formula(options?: TableCellFormulaOptions): void
```

Insert an = (Formula) field with a cached result that Word can update on open.

### `TableCell.getBorder()`

```ts theme={null}
getBorder(location: BorderLocation): TableBorder
```

Live border handle. Reads are effective — direct `w:tcBorders`, else the
style's conditional `w:tblStylePr` borders, else the table's `w:tblBorders`,
else the table style chain — while writes stay direct on this cell.

### `TableCell.getCellPadding()`

```ts theme={null}
getCellPadding(location: CellPaddingLocation): ClientResult<number>
```

Effective cell padding in points: direct `w:tcMar`, else the table's own
`w:tblCellMar`, else the table style chain. Office's ClientResult shape.

### `TableCell.getNext()`

```ts theme={null}
getNext(): TableCell
```

### `TableCell.getNextOrNullObject()`

```ts theme={null}
getNextOrNullObject(): TableCell & { isNullObject: true } | TableCell & { isNullObject: false }
```

### `TableCell.getRange()`

```ts theme={null}
getRange(location?: "Start" | "End" | "Whole"): Range
```

The cell's content as a Range: "Whole" spans every paragraph the cell
owns (nested tables excluded), "Start"/"End" are collapsed carets in its
first/last paragraph. A Whole range is measurable — getRects reports one
rectangle per laid line across all of the cell's paragraphs.

### `TableCell.insertColumns()`

```ts theme={null}
insertColumns(
  location: "Before" | "After",
  columnCount: number,
  values?: string[][],
): void
```

### `TableCell.insertRows()`

```ts theme={null}
insertRows(
  location: "Before" | "After",
  rowCount: number,
  values?: string[][],
): TableRowCollection<TableRow>
```

### `TableCell.insertText()`

```ts theme={null}
insertText(
  text: string,
  location?: CellTextInsertLocation,
  format?: OfficeRunFormatInput,
): Range
```

Newlines split into separate paragraphs inside the cell.

### `TableCell.merge()`

```ts theme={null}
merge(mergeTo: TableCell): void
```

### `TableCell.search()`

```ts theme={null}
search(needle: string, options?: SearchOptions): RangeCollection<Range>
```

### `TableCell.set()`

```ts theme={null}
set(properties: TableCellUpdateData, options?: UpdateOptions): void
```

### `TableCell.setCellPadding()`

```ts theme={null}
setCellPadding(location: CellPaddingLocation, padding: number): void
```

### `TableCell.split()`

```ts theme={null}
split(rowCount: number, columnCount: number): void
```

Split this cell into a rectangular set of cells.

**Not implemented.** These Office.js members throw: `select`.
