Skip to content
LpdfDocsv0.36-r1119.4

Lpdf is pre-release. The XML schema and SDK APIs can change between releases.

Table

Tabular data with explicit column widths, an optional repeating header, and automatic pagination. Tables split between rows — a row will not split mid-cell.

<table cols="…">
<thead> ← optional; repeats at top of each page
<td>…</td>
<td>…</td>
</thead>
<tr> ← data row
<td>…</td>
<td>…</td>
</tr>
</table>
Attribute Type Default Description
cols string — Required. Space-separated column widths: "2fr 1fr 80pt", "40% 60%", or auto for a column the width of its cells: "auto 90pt 60pt". See Column width units
border string — Grid lines between and around the cells
stripe color — The background of every other row below the header, or none
head-border string — The line under the header row: a thickness and a color like border, for example xs line, or none. See Lines and stripes
row-border string — The line under each row, in the same form, or none. Under the header, head-border takes its place when it is set
gap token/length — Space between columns and between rows
padding spacing — Space between the table’s edge and its content. This is not cell padding: set padding on each td
background color or gradient:name — Background behind the whole table: a color, or a gradient that spans the table
width token/length — Constrain table width
paginate string — Page breaks: no break-before break-after keep-next. See Page breaks
bulk boolean false true lays out the rows of its tr with data-source a page at a time, straight from the data, for tables of tens of thousands of rows. See Bulk Records
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

A thead row is repeated at the top of each page. It takes the same background as tr: a color, or a gradient that spans the row, and the same ocg, which puts the row in its group on every page it is repeated on.

Attribute Type Default Description
background color or gradient:name — Row background: a color, or a gradient that spans the row
keep string — with-next keeps the row on the same page as the row after it. See Keeping rows together
data-source string — Dot-path to array — repeats this row per item
data-if string — Render only when value is truthy
data-if-not string — Render only when value is falsy
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content
Attribute Type Default Description
align string fill Horizontal: start center end. By default children fill the cell width
valign string top Vertical: top middle bottom
colspan integer 1 How many columns the cell spans. See Spanning columns
rowspan integer 1 How many rows the cell spans. See Spanning rows
background color or gradient:name — Cell background: a color, or a gradient that spans the cell
padding spacing — Cell inner padding
border string — Cell border
color color inherit Color of the text in the cell. See Text color in a box
data-color string — Dot-path: sets color from the data. See Attributes from data
data-background string — Dot-path: sets background from the data. See Attributes from data
opacity 0–1 1 How opaque the cell and everything in it is. See Opacity
shadow string — A hard-edged shadow under the cell. See Shadow
ocg string — print or screen: shown only in print, or only on screen. See Print and screen content

A table breaks only between rows. A row that does not fit on the page goes to the next page whole, and a header is never left alone at the bottom of a page: when there is no room for the header and a row under it, the table starts on the next page. Both hold without any attribute.

keep="with-next" on a tr keeps it on the same page as the row after it. Put it on a group heading, so that it never ends a page above its first item, and on the rows above a total, so that the total never stands alone:

<table cols="3fr 1fr 1fr" border="xs #e0e0e0">
<thead background="#f0f0f0">
<td padding="xs"><text font-size="xs">Description</text></td>
<td padding="xs" align="end"><text font-size="xs">Qty</text></td>
<td padding="xs" align="end"><text font-size="xs">Amount</text></td>
</thead>
<tr keep="with-next" background="#f9f9f9">
<td padding="xs"><text font-size="xs" bold="true">Design</text></td>
<td padding="xs"><text font-size="xs"> </text></td>
<td padding="xs"><text font-size="xs"> </text></td>
</tr>
<tr>
<td padding="xs"><text font-size="xs">Wireframes</text></td>
<td padding="xs" align="end"><text font-size="xs">12</text></td>
<td padding="xs" align="end"><text font-size="xs">$2,400.00</text></td>
</tr>
<tr keep="with-next">
<td padding="xs"><text font-size="xs">Subtotal</text></td>
<td padding="xs"><text font-size="xs"> </text></td>
<td padding="xs" align="end"><text font-size="xs">$2,400.00</text></td>
</tr>
<tr>
<td padding="xs"><text font-size="xs" bold="true">Total due</text></td>
<td padding="xs"><text font-size="xs"> </text></td>
<td padding="xs" align="end"><text font-size="xs" bold="true">$2,400.00</text></td>
</tr>
</table>

A run of rows that each say with-next, and the row that ends it, form a group. When a page break would fall inside a group, the whole group moves to the next page, under the header that the table repeats there. A group taller than a page cannot stay together: it breaks between its rows as if it had no keep. On the last row of a table, keep has no effect.

colspan="n" on a td makes the cell span n columns. It is as wide as those columns and the gaps between them, and the cells after it in the row start at the column after its last. Use it for a heading across the whole table, and for a label that sits before an amount:

<table cols="4fr 1fr 2fr 2fr" border="xs #e0e0e0">
<thead background="#f0f0f0">
<td padding="xs"><text font-size="xs">Description</text></td>
<td padding="xs" align="end"><text font-size="xs">Qty</text></td>
<td padding="xs" align="end"><text font-size="xs">Price</text></td>
<td padding="xs" align="end"><text font-size="xs">Amount</text></td>
</thead>
<tr background="#f9f9f9">
<td colspan="4" padding="xs"><text font-size="xs" bold="true">Design</text></td>
</tr>
<tr>
<td padding="xs"><text font-size="xs">Wireframes</text></td>
<td padding="xs" align="end"><text font-size="xs">12</text></td>
<td padding="xs" align="end"><text font-size="xs">$200.00</text></td>
<td padding="xs" align="end"><text font-size="xs">$2,400.00</text></td>
</tr>
<tr>
<td colspan="3" padding="xs" align="end"><text font-size="xs">Subtotal</text></td>
<td padding="xs" align="end"><text font-size="xs">$2,400.00</text></td>
</tr>
<tr>
<td colspan="3" padding="xs" align="end"><text font-size="xs" bold="true">Total due</text></td>
<td padding="xs" align="end"><text font-size="xs" bold="true">$2,400.00</text></td>
</tr>
</table>

A cell without colspan takes one column, and a span can start anywhere in a row: the first cell, one in the middle or the last. A row whose cells span more columns than cols names is an error that says how many columns the row spans and how many the table has. A row with fewer leaves its last columns empty.

colspan changes widths only. A row is as tall as its tallest cell at the width that cell has, and page breaks, keep and the repeated header work as they do without it. With a border, the grid has no line inside a spanning cell.

rowspan="n" on a td makes the cell span n rows: its own and the n - 1 under it. It is as tall as those rows and the gaps between them. The rows under it leave its column out, and their cells start at the first free columns, so such a row has fewer cells than the table has columns. Use it for a label that belongs to a group of rows, and for a note that covers several of them:

<table cols="1fr 2fr 2fr 4fr" border="xs #e0e0e0">
<thead background="#f0f0f0">
<td padding="xs"><text font-size="xs">Quarter</text></td>
<td padding="xs"><text font-size="xs">Month</text></td>
<td padding="xs" align="end"><text font-size="xs">Revenue</text></td>
<td padding="xs"><text font-size="xs">Notes</text></td>
</thead>
<tr>
<td rowspan="3" padding="xs"><text font-size="xs" bold="true">Q1</text></td>
<td padding="xs"><text font-size="xs">January</text></td>
<td padding="xs" align="end"><text font-size="xs">$41,200.00</text></td>
<td rowspan="2" padding="xs"><text font-size="xs">Slow start after the holidays.</text></td>
</tr>
<tr>
<td padding="xs"><text font-size="xs">February</text></td>
<td padding="xs" align="end"><text font-size="xs">$38,900.00</text></td>
</tr>
<tr>
<td padding="xs"><text font-size="xs">March</text></td>
<td padding="xs" align="end"><text font-size="xs">$44,100.00</text></td>
<td padding="xs"><text font-size="xs">Spring catalogue sent.</text></td>
</tr>
</table>

The second row has two cells, since the label holds the first column and the note the last. A cell can span columns and rows at once (colspan="2" rowspan="2"). These are errors, and the message says which: a row with more cells than the span leaves free columns for, a colspan that no free columns are wide enough for, a span that runs past the last row of the table, and a rowspan on a thead, which is a single row. Spans are checked in the document as it is written, before data binds, so a data-source that changes the number of rows can leave a row with a cell too many. The cell with no column is left out.

If the content of a spanning cell is taller than the rows it spans together, the last of them grows by the difference. If it is shorter, the cell is stretched to the rows, and valign places its content among all of them.

The rows a cell spans stay on one page. When they do not fit in what is left of a page, they move to the next page together, under the repeated header, and a row with keep="with-next" just above them goes with them. Rows that a cell spans and that are taller than a page are placed whole where they start a page, and cut at the bottom of the page, above the footer. With a border, the grid has no line across a spanning cell: neither the rule under a row nor a rule between two columns inside it.

stripe, head-border and row-border set the rows of a table apart. The lines are drawn across the table, under the row they belong to, and take a thickness and a color as border does. The line color token, a mid grey, and line-muted, a lighter one, are for them.

<table cols="2fr 1fr 1fr" head-border="xs line" row-border="xs line-muted">
<thead>
<td padding="s"><text bold="true">Plan</text></td>
<td padding="s" align="end"><text bold="true">Seats</text></td>
<td padding="s" align="end"><text bold="true">Price</text></td>
</thead>
<tr>
<td padding="s"><text>Starter</text></td>
<td padding="s" align="end"><text>5</text></td>
<td padding="s" align="end"><text>$29</text></td>
</tr>
</table>

A table with head-border alone has the line under its header and none between the rows. One with row-border alone has the same line under every row, the header included. Add stripe="surface-alt" for a stripe as well, with or without the lines. none turns an attribute off, which matters where the table takes a look from styles, as a table of a <markdown> does. A line stops where a cell spans on into the next row, as the grid does. A table that goes on to the next page has its header there again, with its line.

<table cols="3fr 1fr 1fr" border="xs #e0e0e0" stripe="#f9f9f9">
<thead background="#f0f0f0">
<td padding="xs"><text font-size="xs">Description</text></td>
<td padding="xs" align="end"><text font-size="xs">Qty</text></td>
<td padding="xs" align="end"><text font-size="xs">Amount</text></td>
</thead>
<tr data-source="items">
<td padding="xs"><text data-value="description">Item</text></td>
<td padding="xs" align="end"><text data-value="qty">1</text></td>
<td padding="xs" align="end"><text data-value="amount">$0.00</text></td>
</tr>
</table>
Unit Meaning
fr Fraction of remaining width (like CSS fr)
pt, mm, in Fixed width, in points, millimeters or inches
% Percentage of table width
auto The width the cells of the column need on one line

Mixing units is supported: "2fr 80pt 20%", "1fr 40mm". Every column ends up a fixed width in points, worked out from the width of the table. auto mixes with lengths and %, and not with fr, which also shares what is left: "auto 90pt" is allowed and "auto 1fr" is an error that says so. A number with no unit is a share, so "2 1" is "2fr 1fr". An entry that is none of these, such as 40cm, is an error that names it.

An auto column takes the width its cells need to stay on one line, so a column of numbers is as narrow as its numbers and a column of names as wide as its longest name. The auto columns share what the fixed and % columns leave:

  • when every auto column fits on one line, each takes that width, and the room that is left is shared in proportion to it;
  • when they do not fit, each keeps at least its longest word, and shares what is left in proportion to how much more it could use, so the columns of long text are the ones that wrap;
  • when not even the longest words fit, the longest are cut down and a shorter column keeps its width, so a long name goes over two lines and a number never does.
<table cols="auto auto auto" border="xs #e0e0e0" stripe="#f9f9f9">
<thead background="#f0f0f0">
<td padding="xs"><text font-size="s" bold="true">Benchmark</text></td>
<td padding="xs" align="end"><text font-size="s" bold="true">Time (ns/iter)</text></td>
<td padding="xs" align="end"><text font-size="s" bold="true">± (ns)</text></td>
</thead>
<tr>
<td padding="xs"><text font-size="s">parse_xml/small/example1</text></td>
<td padding="xs" align="end"><text font-size="s">12,571</text></td>
<td padding="xs" align="end"><text font-size="s">590</text></td>
</tr>
<tr>
<td padding="xs"><text font-size="s">parse_xml/medium/example8</text></td>
<td padding="xs" align="end"><text font-size="s">273,184</text></td>
<td padding="xs" align="end"><text font-size="s">74,779</text></td>
</tr>
</table>

A table split across pages keeps the widths it has on the first. The tables of a markdown are always auto.