Render an HTML table over NextPDF Connect

At a glance

Render structured tabular data from an HTML table string. add_table sanitizes the input with a strict DOMDocument allowlist before layout, so the output stays consistent even when the source markup varies. Use the Core tools create_pdf, add_table, and output_pdf. The table is laid out as a row/column grid (CSS Tables 3 §3.1).

Install

composer require nextpdf/server

Bind a transport. The input must include a <table> root with <tr> rows and <th>/<td> cells.

Conceptual overview

add_table enforces a fixed element allowlist (table, thead, tbody, tfoot, tr, th, td, caption, b, i, u, strong, em, br, p, span). All attributes are stripped from every element — style, class, width, colspan, rowspan, id, and the rest. Any tag outside the allowlist is replaced with its text content. Cell text uses the document’s active font state, which you set with set_font before add_table. The text is emitted by text-showing operators in content-stream order (ISO 32000-2 §9.4). The layout engine, not inline CSS, decides column widths.

API surface

Tool	Role	Risk tier
`create_pdf`	Open the session	Safe
`set_font`	Set the cell text font (optional, before `add_table`)	Caution
`add_table`	Sanitise and lay out the table	Caution
`output_pdf`	Render and return the PDF	Approval Required / Review (base64)

The tool catalog is the catalog of record. Your available tools depend on the installed tier.

Code sample — Quick start

create_pdf (A4 portrait, title) → document_id.
add_table with a complete <table>...</table> string (header row and data rows).
output_pdf → base64 or, with a file_path, a gated file write.

The cursor moves below the last rendered row, leaving room for the content that follows.

Code sample — Production

Validate the HyperText Markup Language (HTML) before you send it. Set the cell font with set_font for deterministic typography. If you rely on a default, the output font is implementation-dependent. To control which tools the host may call, restrict the registry through the security policy.

Edge cases & gotchas

Empty or non-table HTML. Input with no <table> returns a no-renderable-table error.
Malformed markup. Unbalanced tags return a parse error, so validate the structure first.
Table wider than the page. Reduce columns, shorten the content, or switch to landscape orientation.
Overflow. A tall table flows to a new page. Check position.page in the response, or call add_page ahead of time.

Performance

A small table renders within budget, and the output is a few KB. The profile is structural. Sanitization runs in a single pass over the parsed DOM.

Security notes

Attribute stripping is unconditional and cannot be bypassed. It defends against style and script injection through cell markup. No inline CSS, event handler, or javascript: URL survives. The allowlist is the trust boundary, so do not treat the rendered output as a faithful reproduction of arbitrary source styling.

Conformance

Statement	Spec	Clause	reference_id
Tables are laid out as a row/column cell grid.	CSS Tables 3	§3.1
Text is shown by text operators in stream order.	ISO 32000-2	§9.4

Commercial context

Not applicable — every tool here is Core.

CSS support matrix excerpt (Verified-only)

add_table does not run a general CSS engine. The only “CSS” behavior is the fixed table grid model: rows and columns come from the table structure, and the layout engine chooses the widths. Inline styling is unsupported by design because attributes are stripped. For engine-level (non-Connect) CSS coverage, see the project CSS support matrix.

Single-pass streaming constraint

add_table parses the supplied markup into a DOM once and lays it out in a single pass. It does not reflow against external stylesheets. A table that overflows the page advances to the next page instead of reflowing retroactively.

Memory budget for large tables

Very large tables hold the parsed DOM and laid-out cells in memory for the whole call. Split large datasets across multiple add_table calls to stay within the peak-memory budget.

Transport availability

Transport	Available	Notes
MCP (stdio)	Yes	Large HTML inflates the stdio frame.
REST	Yes	Send the HTML in the request body.
gRPC	Yes	Unary; message-size limits apply.

HITL risk tier

create_pdf is Safe; set_font and add_table are Caution; output_pdf is Approval Required, downgraded to Review in base64 mode. File output stays Approval Required. See output-approval.

Confirmation gate JSON envelope

Base64 output:

{ "allowed": true }

File output returns the challenge envelope that output-approval documents.