Nodes
Table
A grid of cells, with the columns declared once and rows that are ordinary nodes.
The columns belong to the table, because every row shares them — a table whose columns do not line up is not a table. Everything else is an ordinary node: a `.map()` produces rows, a condition drops one, and each names itself. That is what lets a published invoice carry one loop the engine walks rather than a table full of special cases.
- Helpers
- Table, Row, Cell
- Node kind
- table
- Category
- Data
- Resolves
- Static
- Children
- `Row`s, and any `.map()` producing them. A `Row` holds `Cell`s.
| Option | Type | What it does |
|---|---|---|
id | string | Stable address for the node. Engines target it and build artifacts diff on it, so treat a rename as a breaking change. Optional: a node without one takes an id from where it sits, which is what keeps branches and loops from forcing you to invent names. Two nodes claiming one id is an error rather than a race. |
columns required | TableColumn[] | The columns, left to right. Each takes a width in millimetres or "auto" to share what the fixed ones leave, and an align of left, center or right. |
variant | string | A block style the theme looks up — "band", "badge", "panel". Names what the node is, never what it looks like: the appearance lives in the style's blocks, so a document restyles without a node changing. A name the theme has not heard of draws as an ordinary block rather than failing. |
derivers | DeriverInvocation[] | Values the engine computes before the node resolves, written to derived.* and readable from a template token. Built with derive(). These survive publishing and run per document — use them for anything computed from request data. useDeriver runs one during the build instead. |
Writing one
A table needs two things from you: the columns, and the rows. You declare the
columns once on the <Table>, then fill it with <Row>s of <Cell>s.
import { Cell, Row, Table, useFormat, useState } from "docxcelerate/template";
export const VisitLog: Table = () => {
const { number } = useFormat("en-GB");
const [state] = useState((data: MemberData) => ({ months: data.visitsByMonth }));
return (
<Table id="visit-log" columns={[{ width: "auto" }, { width: 28, align: "right" }]}>
<Row header>
<Cell>Month</Cell>
<Cell>Visits</Cell>
</Row>
{state.months.map((entry) => (
<Row>
<Cell>{entry.month}</Cell>
<Cell>{number(entry.visits)}</Cell>
</Row>
))}
</Table>
);
};Each column takes a width — in millimetres, or "auto" to share out whatever
the fixed ones leave — and an optional align.
Why declare columns on the table instead of per cell? Because every row shares them, so declaring them once is what makes the rows line up. It also means a cell only has to say what is in it.
Rows are ordinary nodes
This is the part worth knowing, because it means there is less to learn than you might expect.
Rows and cells are nodes, exactly like a paragraph or a section. So everything you already know works on them:
.map()over your data produces a row per entry, as above.- A condition drops a row, the same way it drops any other node.
- Ids name themselves, so you don’t have to invent one per row.
None of that is special-cased for tables. It is also why a published invoice carries a single loop for the engine to walk, rather than a table full of exceptions.
What a cell holds
Most cells hold a value, so text goes straight in:
<Cell>{line.qty}</Cell>When one line isn’t enough — a description with a quieter note under it — give the cell paragraphs instead, and they stay on separate lines:
<Cell>
<Paragraph>{line.desc}</Paragraph>
<Paragraph variant="muted">{line.meta}</Paragraph>
</Cell>Header rows
Marking a row header draws it as a heading:
<Row header>
<Cell>Description</Cell>
<Cell>Amount</Cell>
</Row>Only the rows a table starts with repeat onto each new page. That matters if you mark a totals row as a header to give it emphasis: it still gets drawn as a heading, but it stays put at the bottom, under the figures it adds up. It won’t be lifted to the top of page two.
Variants
Rows from data
src/nodes/table/basic.node.tsx A header row, then one row per entry from a `.map()`.
import { Cell, Row, Table, useFormat, useState } from "docxcelerate/template";
import type { SampleData } from "../sample-data.ts";
/**
* The columns are declared once, on the table, because every row shares them.
* A row is an ordinary node, so a `.map()` produces one per entry and the
* table needs to know nothing about loops.
*/
export const VisitLog: Table = () => {
const { number } = useFormat("en-GB");
const [state] = useState((data: SampleData) => ({ months: data.visitsByMonth }));
return (
<Table id="visit-log" columns={[{ width: "auto" }, { width: 28, align: "right" }]}>
<Row header>
<Cell>Month</Cell>
<Cell>Visits</Cell>
</Row>
{state.months.map((entry) => (
<Row>
<Cell>{entry.month}</Cell>
<Cell>{number(entry.visits)}</Cell>
</Row>
))}
</Table>
);
};What it resolves to
The node as it appears in the DocumentModel: the JSON a renderer is handed. No styling, no layout.
{
"id": "visit-log",
"kind": "table",
"columns": [
{
"width": "auto"
},
{
"width": 28,
"align": "right"
}
],
"children": [
{
"id": "table-row",
"kind": "tableRow",
"header": true,
"children": [
{
"id": "table-cell",
"kind": "tableCell",
"children": [
{
"id": "table-cell-text",
"kind": "paragraph",
"mode": "static",
"text": "Month"
}
]
},
{
"id": "table-cell-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-2-text",
"kind": "paragraph",
"mode": "static",
"text": "Visits"
}
]
}
]
},
{
"id": "table-row-0",
"kind": "tableRow",
"children": [
{
"id": "table-cell-0",
"kind": "tableCell",
"children": [
{
"id": "table-cell-0-text",
"kind": "paragraph",
"mode": "static",
"text": "Apr"
}
]
},
{
"id": "table-cell-0-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-0-2-text",
"kind": "paragraph",
"mode": "static",
"text": "11"
}
]
}
]
},
{
"id": "table-row-1",
"kind": "tableRow",
"children": [
{
"id": "table-cell-1",
"kind": "tableCell",
"children": [
{
"id": "table-cell-1-text",
"kind": "paragraph",
"mode": "static",
"text": "May"
}
]
},
{
"id": "table-cell-1-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-1-2-text",
"kind": "paragraph",
"mode": "static",
"text": "14"
}
]
}
]
},
{
"id": "table-row-2",
"kind": "tableRow",
"children": [
{
"id": "table-cell-2-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-2-2-text",
"kind": "paragraph",
"mode": "static",
"text": "Jun"
}
]
},
{
"id": "table-cell-2-3",
"kind": "tableCell",
"children": [
{
"id": "table-cell-2-3-text",
"kind": "paragraph",
"mode": "static",
"text": "9"
}
]
}
]
},
{
"id": "table-row-3",
"kind": "tableRow",
"children": [
{
"id": "table-cell-3",
"kind": "tableCell",
"children": [
{
"id": "table-cell-3-text",
"kind": "paragraph",
"mode": "static",
"text": "Jul"
}
]
},
{
"id": "table-cell-3-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-3-2-text",
"kind": "paragraph",
"mode": "static",
"text": "16"
}
]
}
]
},
{
"id": "table-row-4",
"kind": "tableRow",
"children": [
{
"id": "table-cell-4",
"kind": "tableCell",
"children": [
{
"id": "table-cell-4-text",
"kind": "paragraph",
"mode": "static",
"text": "Aug"
}
]
},
{
"id": "table-cell-4-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-4-2-text",
"kind": "paragraph",
"mode": "static",
"text": "18"
}
]
}
]
},
{
"id": "table-row-5",
"kind": "tableRow",
"children": [
{
"id": "table-cell-5",
"kind": "tableCell",
"children": [
{
"id": "table-cell-5-text",
"kind": "paragraph",
"mode": "static",
"text": "Sep"
}
]
},
{
"id": "table-cell-5-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-5-2-text",
"kind": "paragraph",
"mode": "static",
"text": "12"
}
]
}
]
}
]
}A closing row
src/nodes/table/totals.node.tsx A cell holding two paragraphs, and a row marked as a heading.
import { Cell, Paragraph, Row, Table, useFormat, useState } from "docxcelerate/template";
import type { SampleData } from "../sample-data.ts";
/**
* A cell takes text directly, and paragraphs when one line is not enough. The
* closing row is marked `header` so it is drawn as one — it stays where it is,
* because only the rows a table opens with repeat onto a new page.
*/
export const PriceSummary: Table = () => {
const { currency } = useFormat("en-GB");
const [state] = useState((data: SampleData) => ({
plan: data.plan,
lastPrice: data.lastPrice,
newPrice: data.newPrice,
}));
return (
<Table id="price-summary" columns={[{ width: "auto" }, { width: 30, align: "right" }]}>
<Row>
<Cell>
<Paragraph>{state.plan}</Paragraph>
<Paragraph>Last year</Paragraph>
</Cell>
<Cell>{currency(state.lastPrice)}</Cell>
</Row>
<Row header>
<Cell>From renewal</Cell>
<Cell>{currency(state.newPrice)}</Cell>
</Row>
</Table>
);
};What it resolves to
The node as it appears in the DocumentModel: the JSON a renderer is handed. No styling, no layout.
{
"id": "price-summary",
"kind": "table",
"columns": [
{
"width": "auto"
},
{
"width": 30,
"align": "right"
}
],
"children": [
{
"id": "table-row",
"kind": "tableRow",
"children": [
{
"id": "table-cell",
"kind": "tableCell",
"children": [
{
"id": "paragraph",
"kind": "paragraph",
"mode": "static",
"text": "Peak Anytime"
},
{
"id": "paragraph-2",
"kind": "paragraph",
"mode": "static",
"text": "Last year"
}
]
},
{
"id": "table-cell-2",
"kind": "tableCell",
"children": [
{
"id": "table-cell-2-text",
"kind": "paragraph",
"mode": "static",
"text": "£468.00"
}
]
}
]
},
{
"id": "table-row-2",
"kind": "tableRow",
"header": true,
"children": [
{
"id": "table-cell-3",
"kind": "tableCell",
"children": [
{
"id": "table-cell-3-text",
"kind": "paragraph",
"mode": "static",
"text": "From renewal"
}
]
},
{
"id": "table-cell-4",
"kind": "tableCell",
"children": [
{
"id": "table-cell-4-text",
"kind": "paragraph",
"mode": "static",
"text": "£492.00"
}
]
}
]
}
]
}Notes
- An empty cell is still a cell. Word won’t accept a truly empty one, so it packs as a blank box rather than a column that has gone missing.
spanruns a cell across several columns.alignoverrides its column’s alignment for that one cell.- If you set a
varianton a cell, it wins over one on the row, which wins over one on the table. The more specific one is usually the one you meant. - Both renderers draw a real table — a
<table>on screen, and a Word table with your declared column widths in the.docx.