Field

Last updated on

Field is the leaf of every composition: the smallest thing that reads from the artifact and prints something a person can read. It carries no layout of its own beyond its label, and it is always a KeepTogether, so a page break never separates a label from the value underneath it.

Preview

Installation

npx shadcn@4 add @paradoc/field

npx paradoc-cli add field

Usage

import { Field } from "@/components/paradoc/field";<Field path="provider" />

Composition

Field always sits inside a Document: it reads the current artifact and its data through context that only Document provides, and rendering one outside a Document throws. Most fields sit inside a Section that groups them under a heading, but nothing requires that — the Preview above renders three Fields directly inside Document, with no Section around them.

The path prop follows Paradoc's shared path grammar: a top-level field name like customer, or a path into a list item like lineItems[0].unitPrice. Numeric indexes can also use dot notation (lineItems.0.unitPrice). Empty segments and the unsafe object members __proto__, prototype, and constructor are rejected. Field does not validate or format anything itself — it asks the artifact for the field at that path and the value's serializer for the text to print.

Every Field is a Keep Together, which it brings along automatically, and that is also its whole pagination story: a field is never split across a page break, and it renders only on the page the plan assigned it to. A Table's cells reuse the same serializers a Field does, just as flex cells rather than as Field instances.

A newline inside a value is a line break in both outputs — the value is drawn with whitespace-pre-line, so a value typed on three lines prints on three lines. A newline never paginates: a blank line only splits the value into paragraphs when paragraphs is set, and then each paragraph is its own pagination unit. Without it, a value longer than a page is one keep, and a keep that does not fit the page opened for it overflows and is reported as oversize.

The label's size follows the document's typography token; the value inherits the root's.

as="image" prints the other thing a document binds by path: an attachment. An attachment is not a field value — the artifact declares annex slots and the filled data carries one per slot — so the path is annexes.<slot>, the heading comes from the slot's own title, and width and height say how big to draw it. An attachment whose MIME type is not a picture prints its file name instead, and paradoc check reports the mismatch. See Image.

Variants

Beyond path and className, Field takes label, which can be omitted (uses the artifact's own label), set to false (no label), or overridden with a string; paragraphs, which splits a long value into one pagination unit per paragraph; and rule, which draws a fill line where a value is missing. paragraphs and rule apply to text only. as, width, height and src belong to the attachment form above, and are shown on Image.

Default label

With no label prop, the heading comes from the artifact's own field definition.

No label

label={false} renders the value alone, with no heading above it.

Custom label

A string label overrides the artifact's own.

Paragraphs

paragraphs splits the value at its blank lines and gives each paragraph its own keep, field:<path>:<index>, so long prose breaks between paragraphs at a page boundary rather than overflowing as one oversize unit. The label stays with the first paragraph. A single paragraph taller than a page is still oversize: a pagination unit is never split inside itself.

Fill line

rule draws an underscore run where the artifact has no value, instead of the document's blank placeholder — a document printed for somebody to write on rather than one nobody will.