Text

Text puts words on the page. Pass a string and a few options, and the engine wraps it to fit the width it is given, breaking on word boundaries using the real font metrics. You never measure anything.

When does it wrap?

A Text wraps to fit the width it is given - the page content width in a Page or Column, or the width of a Box({ width }), an Expanded or a table cell when it sits inside one. With no width limit at all (a plain child of a Row), it stays on a single line, because there is nothing to wrap against.

Styling

The second argument sets the style. Everything is optional and has a sensible default.

Text("Big and bold", { size: 26, bold: true, color: "#1450aa" });
Text("A quiet note", { size: 12, italic: true, color: "gray" });

Alignment

align positions the text inside its own block, independent of any surrounding layout.

Text("Centered", { align: "center" });
Text("Right aligned", { align: "right" });

Line height

lineHeight is a multiplier on the line spacing. Leave it unset and each line gets the font's own natural line height - the same thing CSS calls line-height: normal, so text is comfortable to read out of the box and capitals sit optically centred in their line. Set a number to override it: 1 is one em (tight, capitals may just touch the edges), 1.3 to 1.5 opens body copy up further. Whatever the value, the extra space is split evenly above and below each line.

Text("Comfortable by default - the font's natural line height.");
Text("Airier still, set once.", { lineHeight: 1.5 });

Underline, strikethrough and letter spacing

Decoration and tracking read their geometry from the font itself, never a hard-coded guess.

Text("Underlined", { underline: true });
Text("Struck through", { strikethrough: true });
Text("S P A C E D  H E A D E R", { letterSpacing: 3, bold: true });
Text("tighter", { letterSpacing: -0.5 });

An underline sits at the position and thickness the font declares, one stroke per wrapped line, and a struck-through line crosses at half the x-height - where a browser puts it. letterSpacing adds a fixed gap after every glyph (a negative value tightens); it is counted in wrapping and alignment, so spaced text still breaks and aligns correctly. All of these also work on a single span and cascade from Document / DefaultTextStyle.

skipInk lets the underline break around descenders like a browser does - it needs an embedded font (the standard PDF fonts keep their outlines in the viewer, not in the document), and asking for it with a standard font is an error rather than a silent no-op.

Kerning

Text is kerned by default: the font's own pair adjustments tighten letter combinations like AV, To and Wa, so headings read the way they do on the web instead of falling into loose slabs. It works for the standard fonts and for embedded fonts (both the legacy kern table and modern OpenType GPOS). Pass { kerning: false } to renderToBytes / renderPdf to turn it off.

await renderToBytes(doc); // kerned
await renderToBytes(doc, { kerning: false }); // no kerning, byte-for-byte as before

Inheriting text styles

Every option above has a built-in default, but you rarely want to repeat size or color on every line. Set them once and let them cascade - exactly like CSS, or Flutter's DefaultTextStyle.

Document-wide defaults

Pass the text options to Document and every Text inherits them unless it sets its own. This is the cleanest way to give a whole document one consistent typeface, size, colour and rhythm.

Document({ font: "Times-Roman", size: 11, color: "#1f2a37", lineHeight: 1.5 }, [
  Page({ size: "A4" }, [
    Text("Inherits the serif, 11pt, dark ink and 1.5 line-height."),
    Text("Sets nothing either - identical to the line above."),
    Text("Overrides just the colour; size, font and line-height still inherit.", {
      color: "#c0392b",
    }),
  ]),
]);

A default for one section - DefaultTextStyle

To re-default a section instead of the whole document, wrap it in DefaultTextStyle. Its children inherit the new values, layered onto whatever was already inherited from above.

DefaultTextStyle({ size: 9, color: "gray" }, [
  Text("Small and grey - a footnote, a caption, a contact block."),
  Text("Same here, nothing set on it."),
  Text("Still 9pt, but overrides the colour.", { color: "#1450aa" }),
]);

To style one whole page, make it the page's child: Page([ DefaultTextStyle({ … }, [ …content ]) ]).

How a value is resolved

For each property the most specific source wins - and only that property; the rest keep inheriting (a per-property merge, like Flutter):

explicit on the Text  >  nearest DefaultTextStyle  >  Document defaults  >  built-in default

Only text properties inherit - font, size, color, bold, italic, align, lineHeight, the same set CSS inherits. Box and layout properties (padding, border, width, background) never do.

Truncating long text

By default a Text wraps onto as many lines as it needs. Cap it with maxLines, and choose what happens to the overflow with overflow: "clip" cuts hard, "ellipsis" ends the last line with .... Truncation needs a bounded width - a Column, a Box({ width }), an Expanded or a table cell.

Box({ width: 220 }, [
  Text("Premium Wireless Noise-Cancelling Over-Ear Headphones with 40 Hour Battery Life", {
    maxLines: 2,
    overflow: "ellipsis",
  }),
]);

maxLines: 1 clamps to a single line - handy for a long product name in a narrow table cell.

Mixed styles in one line

To change style partway through a line, pass an array of span(...) runs instead of a string. Each span overrides only the fields it sets, inheriting the rest from the Text options.

import { Text, span } from "@jasy/pdf";

Text(
  [
    span("This line mixes "),
    span("bold", { bold: true }),
    span(", "),
    span("italic", { italic: true }),
    span(" and "),
    span("color", { color: "#1450aa", bold: true }),
    span(" in one run."),
  ],
  { size: 14 },
);

span takes the same TextStyle as Text (size, font, bold, italic, color), just no align, since alignment belongs to the whole block.

Paragraphs

Paragraph is Text with a different name. It behaves identically, but reads as intent when you mean a block of body copy rather than a label or a heading.

Paragraph(
  "Long text wraps automatically to fit its width, breaking on word boundaries using the real " +
    "font metrics, so you never have to measure anything yourself.",
  { size: 12 },
);

See it all in one file

Copy this, run it with npx tsx text-demo.ts, and open text.pdf.

import { writeFileSync } from "node:fs";
import { Document, Page, Column, Text, Paragraph, span, Divider, renderToBytes } from "@jasy/pdf";

async function build() {
  const doc = Document([
    Page({ size: "A4", margin: 56 }, [
      Column({ gap: 12 }, [
        Text("Big and bold", { size: 26, bold: true, color: "#1450aa" }),
        Text("Italic and gray", { size: 14, italic: true, color: "gray" }),
        Text("Centered", { size: 14, align: "center" }),
        Text("Right aligned", { size: 14, align: "right" }),
        Divider({ color: "steelblue" }),
        Text(
          [
            span("This line mixes "),
            span("bold", { bold: true }),
            span(", "),
            span("italic", { italic: true }),
            span(" and "),
            span("color", { color: "#1450aa", bold: true }),
            span(" in one run."),
          ],
          { size: 14 },
        ),
        Divider({ color: "steelblue" }),
        Paragraph(
          "Paragraph is Text with a name that reads as intent. Long text wraps automatically to fit " +
            "its width, breaking on word boundaries using the real font metrics, so you never measure " +
            "anything yourself.",
          { size: 12 },
        ),
      ]),
    ]),
  ]);

  writeFileSync("text.pdf", await renderToBytes(doc));
}

build();