---
title: "PagesTableKit: tables for the Pages extension"
description: "Table extensions tailored for the Pages pagination extension. Works for any Pages setup; pairs with DOCX import for faithful Word-document rendering. Experimental feature; the API may change."
canonical_url: "https://tiptap.dev/docs/pages/guides/pages-tablekit"
---

# PagesTableKit: tables for the Pages extension

Table extensions tailored for the Pages pagination extension. Works for any Pages setup; pairs with DOCX import for faithful Word-document rendering. Experimental feature; the API may change.

> **Experimental feature:**
>
> PagesTableKit is built specifically for the Pages extension. APIs and rendering behaviour may
> change without notice. Pin exact package versions if you depend on it. Read the **What won't
> work** section before adopting it.

- **1. Activate trial or subscribe**

  Start a [free trial](https://cloud.tiptap.dev/v2?trial=true) or [subscribe to the Start
  plan](https://cloud.tiptap.dev/v2/billing) in your account.
- **2. Install from private registry**

  Authenticate to Tiptap's private npm registry by following the [setup
  guide](https://tiptap.dev/docs/guides/pro-extensions.md).

## Which setup applies to me?

> **Two scenarios, one editor stack:**
>
> PagesTableKit is useful in two scenarios that differ in how the table content gets there, not in
> how you wire up the editor. The base extensions are the same; the second scenario adds the Import
> extension on top.

- **Pages-only workflow.** You are building a paginated editor (print-ready layouts, letter-style documents, reports) and you need tables that paginate correctly. Content is hand-authored.
- **Pages + DOCX import workflow.** You are importing `.docx` files and rendering them in a paginated editor. You need tables that paginate **and** faithfully reflect the authored DOCX formatting (declared widths, row heights, indentation).

Both scenarios use the same editor stack: `ConvertKit` (for the schema) + `TableKit` (for pagination-safe tables) + `Pages` (for the layout). Scenario B adds `ImportDocx`. Each section below flags which scenario it applies to.

> **Interactive demo:** [ImportDocxCssStylesPages](https://embed-pro.tiptap.dev/preview/Extensions/ImportDocxCssStylesPages)

## Install

```bash
npm i @tiptap-pro/extension-convert-kit \
      @tiptap-pro/extension-pages-tablekit \
      @tiptap-pro/extension-pages
```

For Scenario B, also install:

```bash
npm i @tiptap-pro/extension-import-docx
```

## How to set it up

PagesTableKit ships a single `TableKit` extension that bundles the Table, TableRow, TableCell, and TableHeader extensions. Register it once instead of wiring up the four extensions individually.

### Scenario A: Pages-only (no DOCX import)

Register `ConvertKit` (with its built-in table stack disabled), `TableKit` from PagesTableKit, and `Pages`.

```ts
import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }), // disable ConvertKit's tables
    TableKit,
    Pages.configure({
      /* page format, margins, etc. */
    }),
  ],
})
```

ConvertKit supplies the document's node and mark schema; PagesTableKit's `TableKit` supplies the pagination-safe tables. ConvertKit's built-in `ConvertTableKit` is **not** pagination-safe, which is why we disable it here.

### Scenario B: Pages + DOCX import

Add the [ImportDocx extension](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md) on top of the same stack. ConvertKit's tables stay disabled; PagesTableKit's `TableKit` accepts the same DOCX cell attributes that ConvertKit's tables would, so imported tables render correctly with pagination.

```ts
import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { ImportDocx } from '@tiptap-pro/extension-import-docx'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    ImportDocx.configure({
      /* appId, token, … */
    }),
    Pages.configure({
      /* page format, margins, etc. */
    }),
  ],
})
```

## What works

### Universal behaviour (both scenarios)

- **Pagination-safe table rendering.** Tables sit inside the page content area and never horizontally overflow it.
- **Column proportions preserved.** When every cell carries a `colwidth`, columns shrink proportionally to fit the page. A 10 % / 40 % / 50 % column split renders as 10 / 40 / 50 at any page width.
- **Row height behaviour.**
  - `heightRule: "exact"`: the row renders at the declared height and clips overflowing content.
  - `heightRule: "atLeast"` (or unset): the row grows vertically when content or narrower columns would otherwise force clipping.
- **Live updates.** Edits that add, remove, or reorder cells re-lay the row out immediately.

### DOCX-specific behaviour (Scenario B)

These extras activate automatically when your document content was produced by the DOCX importer. You don't configure them separately; if the converter emitted the attribute, PagesTableKit honours it.

- **Declared DOCX widths respected.** A DOCX table authored wider than the page shrinks proportionally into the content area instead of overflowing.
- **DOCX row heights.** `w:trHeight` with `w:hRule="exact"` clips; `w:hRule="atLeast"` (or missing) grows.
- **Narrow spacer columns preserved.** DOCX spacer columns (1–15 px) don't get inflated to a visible width.
- **Negative DOCX indents.** Negative `w:tblInd` values (which Word renders into the paper gutter) are preserved in `attrs.indent` but clamped to 0 visually so tables don't push past the page edge.
- **Cell background, vertical alignment, per-side borders.** Flow through from the DOCX import without extra work.

## What won't work

> **These are intentional limits:**
>
> These are not bugs. They are explicit, documented boundaries of the feature. If your workflow
> depends on any of the items below, this feature is not the right tool.

### Universal limits (both scenarios)

- **Editors without the Pages extension.** PagesTableKit is designed for Pages' paginated layout; it relies on Pages to constrain rows within the page. In a standard editor rows won't render correctly and over-wide tables will overflow horizontally. Use a regular table extension instead.
- **Hand-authored rows with mixed `colwidth` / no `colwidth`.** The proportional-shrink behaviour kicks in when **every** cell carries a column width. In rows where some cells do and some don't, columns may render with different proportions than you'd expect.
- **Column resize handles.** Drag-to-resize from `@tiptap/extension-table` is supported, but the final rendered widths may be proportional rather than the exact pixel values you dragged to, especially when every cell already carries a column width.

### DOCX-specific limits (Scenario B)

- **Floating tables.** DOCX `w:tblpPr` (tables positioned relative to an anchor with text wrap) is not converted by the importer; floats render as regular stacked tables.
- **Pixel-perfect parity with Microsoft Word's table layout.** Word uses a proprietary layout algorithm that blends fixed and proportional sizing with content measurement. Expect small differences on tables authored with Word's "AutoFit to contents" setting.

## Known issues

### Rows must fit on a single page

When a table row does not fit on the current page, Pages moves the **entire row** to the next page as an atomic unit. This differs from Microsoft Word, which visually splits a tall row across pages. PagesTableKit does not currently support mid-row page splits.

If a row is taller than the page content area, moving it to the next page doesn't help: it won't fit there either, and the editor will keep trying to move it forward indefinitely. The result is an infinite pagination loop and a broken editor.

**How to avoid it.** Keep row heights below the page content area. Be especially careful with:

- `heightRule: "atLeast"` rows whose content can grow unbounded.
- DOCX imports that carry very tall exact-height rows authored for larger paper than your target page format.
- Nested tables inside cells, which can force the outer row taller than the page.

Mid-row page splitting is on the roadmap. ETA: TBD.

## What to expect

### Universal (both scenarios)

- Tables sit inside the page content area; exact-height rows clip, `atLeast` rows grow.
- Updates land on every transaction; adding or removing cells re-lays the row immediately.
- Very large tables (thousands of rows) may have a noticeable layout cost on edits. If you hit this, consider paginating large tables manually or splitting them across multiple documents.

### DOCX-specific (Scenario B)

- DOCX tables retain their declared widths, row heights, indentation, background colours, and per-side borders on import.
- Over-wide DOCX tables (common in templates drawn full-width in Word) visually shrink to fit the page instead of overflowing.
- You do not need to post-process imported DOCX JSON before rendering; the extensions read the attributes the importer produces.

## What not to expect

### Universal (both scenarios)

- **A replacement for Pages.** PagesTableKit only handles tables. Pagination, page containers, headers, and footers are Pages' responsibility.
- **Column-width mutation from your own DOM code.** Column widths flow from the ProseMirror document. Change them via `@tiptap/extension-table`'s commands (or your own transactions), not by writing directly to `dom.style`.

### DOCX-specific (Scenario B)

- **Round-trip identity.** Importing then exporting a DOCX through the Convert pipeline is not guaranteed to be byte-identical. Unsupported DOCX features (floats, certain table styles) are dropped on import.

## Configuration reference

PagesTableKit exports a single `TableKit` extension that bundles Table, TableRow, TableCell, and TableHeader.

```ts
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'

// Use defaults
TableKit,
```

Each bundled extension can be configured (or disabled with `false`) through `TableKit.configure()`:

```ts
TableKit.configure({
  table: { cellMinWidth: 1 }, // Table options from @tiptap/extension-table
  tableRow: {
    /* TableRow options */
  },
  tableCell: {
    /* TableCell options */
  },
  tableHeader: false, // disable the header extension entirely
})
```

There are no configuration options unique to PagesTableKit; each key forwards to the underlying extension's standard options.

## Related

- [Pages overview](https://tiptap.dev/docs/pages/getting-started/overview.md): the pagination extension PagesTableKit requires.
- [Pages with tables](https://tiptap.dev/docs/pages/guides/table-with-pages.md): general guide for authoring tables inside Pages.
- [ConvertKit](https://tiptap.dev/docs/conversion/import/docx/convertkit.md): DOCX-aware editor kit; use it for Scenario B.
- [Editor extension (import DOCX)](https://tiptap.dev/docs/conversion/import/docx/editor-extension.md): how the `ImportDocx` extension pulls Word content into your editor.
- [CSS injection (import)](https://tiptap.dev/docs/conversion/import/docx/css-injection.md): extract the DOCX style catalog as CSS for consistent typography across paginated content.