Text
A flow text block. Supports multi-line wrapping, font styling, and inline span children for mixed runs.
Text has one set of defaults wherever it is, in the flow and in a layer: the document’s font or Helvetica, 11pt (m) and the text color. In the flow, a text takes its font, font-size and color from the nearest box that sets them.
Attributes
Section titled “Attributes”| Attribute | Type | Default | Description |
|---|---|---|---|
font-size |
token/length | inherit, else m (11pt) |
xs s m l xl xxl or 14pt |
font |
string | inherit, else the document’s font, or Helvetica |
Font name declared in assets |
color |
color | the nearest box’s, else #1a1a1a |
Text color: a color, such as #333333 or cmyk(0, 0, 0, 80), or a named token. A text that sets none takes the color of the nearest box that sets one, else the text color: a color named text in tokens changes the default. See Text color in a box |
align |
string | left |
left center right justify. Not inherited: on a box, align places the children |
width |
token/length | — | Constrain text block width |
line-height |
number or token | 1.2 (m) |
The distance between lines, as a factor of the font size: a number above 0, or a name from the line-height row of tokens. See Line height |
max-lines |
integer | — | The most lines drawn. Only whole lines are drawn, and the rest of the text is dropped. No cap by default: the text wraps whole. See Capping a text |
ellipsis |
boolean | false |
End the last line drawn in an ellipsis when max-lines drops text. With no max-lines it changes nothing |
role |
string | — | h1 … h6: makes the text a heading, which a tagged document, with pdfua or a pdfa of level a, tags as one. It changes nothing a page shows. A document that is not tagged ignores it |
widows |
integer | 2 |
The fewest lines, 1 to 10, that a split paragraph may carry to the top of the next page. See Widows and orphans |
orphans |
integer | 2 |
The fewest lines, 1 to 10, that a split paragraph may leave at the bottom of a page |
capture |
string | — | Records the words of this text under a name, for a header or a footer to show. See Running headers |
capture-ref |
string | — | In a region: shows what was recorded under the name, as of its page, in place of words of its own |
capture-mode |
string | last |
With capture-ref: first or last, which of the texts captured on the page it shows |
capture-fallback |
string | — | With capture-ref: what it shows until something has been captured in the section |
paginate |
string | — | Page breaks: no break-before break-after keep-next. See Page breaks |
data-value |
string | — | Dot-path — replaces text content with bound value |
data-if |
string | — | Render only when value is truthy |
data-if-not |
string | — | Render only when value is falsy |
data-color |
string | — | Dot-path: sets color from the data. See Attributes from data |
ocg |
string | — | print or screen: shown only in print, or only on screen. See Print and screen content |
<text font-size="24pt">Heading</text><text font-size="m" color="#555555">Supporting paragraph text.</text>Justified body copy
Section titled “Justified body copy”<text font-size="m" align="justify"> Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically.</text>L.text({ fontSize: 'm', align: 'justify' }, ['Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically.'])L.text(TextAttr(font_size='m', align='justify'), ['Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically.'])L.text(new TextAttr().fontSize("m").align("justify"), List.of("Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically."))L.Text(new() { FontSize = "m", Align = "justify" }, ["Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically."])L::text(new TextAttr(fontSize: 'm', align: 'justify'), ['Long paragraphs of body copy look best with justify alignment. The engine handles line breaking automatically.'])Inline spans for mixed styling
Section titled “Inline spans for mixed styling”Use span children to apply different styles within a single text block.
| Span attribute | Description |
|---|---|
font |
Font name |
color |
Text color |
href |
Makes the span a link: a URL, or #id to jump to the bookmark with that id |
bookmark-ref |
Makes the span a cross-reference to the bookmark with that id: a link to it, whose words can print its page, {bookmark-page}, and its label, {bookmark-label}. See Referring to a bookmark |
underline |
true / false |
strike |
true / false |
<text font-size="m"> See the <span href="https://lpdf.io" color="#1a73e8" underline="true">documentation</span> for full details. Use <span font="Courier">monospace</span> for code.</text>L.text({ fontSize: 'm' }, [ 'See the ', L.span({ href: 'https://lpdf.io', color: '#1a73e8', underline: true }, ['documentation']), ' for full details. Use ', L.span({ font: 'Courier' }, ['monospace']), ' for code.',])L.text(TextAttr(font_size='m'), [ 'See the ', L.span(SpanAttr(href='https://lpdf.io', color='#1a73e8', underline=True), ['documentation']), ' for full details. Use ', L.span(SpanAttr(font='Courier'), ['monospace']), ' for code.'])L.text(new TextAttr().fontSize("m"), List.of( "See the ", L.span(new SpanAttr().href("https://lpdf.io").color("#1a73e8").underline(true), List.of("documentation")), " for full details. Use ", L.span(new SpanAttr().font("Courier"), List.of("monospace")), " for code."))L.Text(new() { FontSize = "m" }, [ "See the ", L.Span(new() { Href = "https://lpdf.io", Color = "#1a73e8", Underline = true }, ["documentation"]), " for full details. Use ", L.Span(new() { Font = "Courier" }, ["monospace"]), " for code.",])L::text(new TextAttr(fontSize: 'm'), [ 'See the ', L::span(new SpanAttr(href: 'https://lpdf.io', color: '#1a73e8', underline: true), ['documentation']), ' for full details. Use ', L::span(new SpanAttr(font: 'Courier'), ['monospace']), ' for code.',])Spaces around a span
Section titled “Spaces around a span”A span is joined to the text around it as the XML is written: a space falls between them only where the text has whitespace there. Total: <span>5</span> reads “Total: 5”, and $<span>5</span> reads “$5”.
<column gap="xs"> <text>Total: <span bold="true">5</span> units</text> <text>$<span bold="true">5</span>.00</text></column>L.column({ gap: 'xs' }, [ L.text(NoAttr, [ 'Total: ', L.span({ bold: true }, ['5']), ' units', ]), L.text(NoAttr, [ '$', L.span({ bold: true }, ['5']), '.00', ]),])L.column(ColumnAttr(gap='xs'), [ L.text(NoAttr, [ 'Total: ', L.span(SpanAttr(bold=True), ['5']), ' units' ]), L.text(NoAttr, [ '$', L.span(SpanAttr(bold=True), ['5']), '.00' ])])L.column(new ColumnAttr().gap("xs"), List.of( L.text(NoAttr, List.of( "Total: ", L.span(new SpanAttr().bold(true), List.of("5")), " units" )), L.text(NoAttr, List.of( "$", L.span(new SpanAttr().bold(true), List.of("5")), ".00" ))))L.Column(new() { Gap = "xs" }, [ L.Text(NoAttr, [ "Total: ", L.Span(new() { Bold = true }, ["5"]), " units", ]), L.Text(NoAttr, [ "$", L.Span(new() { Bold = true }, ["5"]), ".00", ]),])L::column(new ColumnAttr(gap: 'xs'), [ L::text(NoAttr, [ 'Total: ', L::span(new SpanAttr(bold: true), ['5']), ' units', ]), L::text(NoAttr, [ '$', L::span(new SpanAttr(bold: true), ['5']), '.00', ]),])The strings and spans you give text in code are joined the same way, so the space belongs inside the string, as the tabs above show: 'Total: ' reads “Total: 5”, and 'Total:' before the same span reads “Total:5”.
A line break and the indentation after it count as one space. A space at the start or end of the text is dropped, and so is one at the start of a span. One at the end of a span separates it from what follows.
Code in a line
Section titled “Code in a line”A code-span is a span for code: its words in Courier on a light tint. A block of code, which keeps its spaces and lines, is a code.
<text>Run <code-span>cargo test</code-span> before you push.</text>L.text(NoAttr, [ 'Run ', L.codeSpan(NoAttr, ['cargo test']), ' before you push.',])L.text(NoAttr, [ 'Run ', L.code_span(NoAttr, ['cargo test']), ' before you push.'])L.text(NoAttr, List.of( "Run ", L.codeSpan(NoAttr, List.of("cargo test")), " before you push."))L.Text(NoAttr, [ "Run ", L.CodeSpan(NoAttr, ["cargo test"]), " before you push.",])L::text(NoAttr, [ 'Run ', L::codeSpan(NoAttr, ['cargo test']), ' before you push.',])Footnotes
Section titled “Footnotes”An fn inside a text puts a small raised number in the line and its note at the bottom of the page where the number lands. See Footnote.
Widows and orphans
Section titled “Widows and orphans”When a paragraph splits across pages, Lpdf keeps at least two of its lines on each page. A line left alone at the bottom of a page is an orphan, and one carried alone to the top of the next page is a widow.
- When fewer than
orphanslines fit at the bottom of the page, the whole paragraph moves to the next page. - When fewer than
widowslines would go to the next page, lines move there from the first page, so the first page ends earlier. widows="1"andorphans="1"turn this off: the paragraph splits wherever the page ends.- A paragraph that cannot keep both, even at the top of an empty page, splits where the lines fit.
<text widows="3" orphans="3"> A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one.</text>L.text({ widows: 3, orphans: 3 }, ['A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one.'])L.text(TextAttr(widows=3, orphans=3), ['A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one.'])L.text(new TextAttr().widows(3).orphans(3), List.of("A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one."))L.Text(new() { Widows = 3, Orphans = 3 }, ["A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one."])L::text(new TextAttr(widows: 3, orphans: 3), ['A paragraph that never leaves fewer than three of its lines on a page, at the bottom of the first page or at the top of the next one.'])Capping a text
Section titled “Capping a text”A text wraps at the width it has and is never cut: a long name or address makes its line, and in a table its whole row, as tall as it needs. A word, or a styled run, wider than a whole line breaks at the last character that fits, so nothing runs past the box. max-lines caps it. Only whole lines are drawn, and the rest of the text is dropped. The lines it drops take no room, so a capped text is only as tall as the lines it keeps.
ellipsis="true" ends the last line in dots when text was dropped, shortened to fit the width. Without it the text stops at the end of the last line. On its own, with no max-lines, ellipsis changes nothing: a text with no cap is never cut, and a word wider than the box is broken at the last character that fits, not cut.
A table with a long name in a cell, kept to two lines:
<table cols="3fr 1fr" border="xs #e0e0e0"> <tr> <td padding="s"> <text max-lines="2" ellipsis="true">A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for</text> </td> <td padding="s"><text align="right">19.00</text></td> </tr> <tr> <td padding="s"><text max-lines="2" ellipsis="true">A short name</text></td> <td padding="s"><text align="right">4.50</text></td> </tr></table>L.table({ cols: '3fr 1fr', border: 'xs #e0e0e0' }, [ L.tr(NoAttr, [ L.td({ padding: 's' }, [ L.text({ maxLines: 2, ellipsis: true }, ['A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for']), ]), L.td({ padding: 's' }, [ L.text({ align: 'right' }, ['19.00']), ]), ]), L.tr(NoAttr, [ L.td({ padding: 's' }, [ L.text({ maxLines: 2, ellipsis: true }, ['A short name']), ]), L.td({ padding: 's' }, [ L.text({ align: 'right' }, ['4.50']), ]), ]),])L.table(TableAttr(cols='3fr 1fr', border='xs #e0e0e0'), [ L.tr(NoAttr, [ L.td(TdAttr(padding='s'), [ L.text(TextAttr(max_lines=2, ellipsis=True), ['A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for']) ]), L.td(TdAttr(padding='s'), [ L.text(TextAttr(align='right'), ['19.00']) ]) ]), L.tr(NoAttr, [ L.td(TdAttr(padding='s'), [ L.text(TextAttr(max_lines=2, ellipsis=True), ['A short name']) ]), L.td(TdAttr(padding='s'), [ L.text(TextAttr(align='right'), ['4.50']) ]) ])])L.table(new TableAttr().cols("3fr 1fr").border("xs #e0e0e0"), List.of( L.tr(NoAttr, List.of( L.td(new TdAttr().padding("s"), List.of( L.text(new TextAttr().maxLines(2).ellipsis(true), List.of("A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for")) )), L.td(new TdAttr().padding("s"), List.of( L.text(new TextAttr().align("right"), List.of("19.00")) )) )), L.tr(NoAttr, List.of( L.td(new TdAttr().padding("s"), List.of( L.text(new TextAttr().maxLines(2).ellipsis(true), List.of("A short name")) )), L.td(new TdAttr().padding("s"), List.of( L.text(new TextAttr().align("right"), List.of("4.50")) )) ))))L.Table(new() { Cols = "3fr 1fr", Border = "xs #e0e0e0" }, [ L.Tr(NoAttr, [ L.Td(new() { Padding = "s" }, [ L.Text(new() { MaxLines = 2, Ellipsis = true }, ["A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for"]), ]), L.Td(new() { Padding = "s" }, [ L.Text(new() { Align = "right" }, ["19.00"]), ]), ]), L.Tr(NoAttr, [ L.Td(new() { Padding = "s" }, [ L.Text(new() { MaxLines = 2, Ellipsis = true }, ["A short name"]), ]), L.Td(new() { Padding = "s" }, [ L.Text(new() { Align = "right" }, ["4.50"]), ]), ]),])L::table(new TableAttr(cols: '3fr 1fr', border: 'xs #e0e0e0'), [ L::tr(NoAttr, [ L::td(new TdAttr(padding: 's'), [ L::text(new TextAttr(maxLines: 2, ellipsis: true), ['A product name so long that it would wrap onto a third and a fourth line and make this whole row tall, when two lines are all the table has room for']), ]), L::td(new TdAttr(padding: 's'), [ L::text(new TextAttr(align: 'right'), ['19.00']), ]), ]), L::tr(NoAttr, [ L::td(new TdAttr(padding: 's'), [ L::text(new TextAttr(maxLines: 2, ellipsis: true), ['A short name']), ]), L::td(new TdAttr(padding: 's'), [ L::text(new TextAttr(align: 'right'), ['4.50']), ]), ]),])A capped text that splits across pages keeps the cap across them: the lines it keeps are never more than max-lines.
Line height
Section titled “Line height”The distance between lines is a factor of the font size: 1.2 by default, so an 11pt text has 13.2pt lines. Give a number above 0, such as 1.5, or a name from the line-height row of tokens: xs is 1.0, s 1.1, m 1.2, l 1.4, xl 1.6 and xxl 2.0. A text without line-height is the same as one with line-height="m".
A text splits across pages by its own line height, so open lines break where the page ends.
<column gap="m"> <text line-height="1.6">Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them.</text> <text line-height="xs">Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table.</text></column>L.column({ gap: 'm' }, [ L.text({ lineHeight: 1.6 }, ['Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them.']), L.text({ lineHeight: 'xs' }, ['Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table.']),])L.column(ColumnAttr(gap='m'), [ L.text(TextAttr(line_height=1.6), ['Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them.']), L.text(TextAttr(line_height='xs'), ['Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table.'])])L.column(new ColumnAttr().gap("m"), List.of( L.text(new TextAttr().lineHeight(1.6), List.of("Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them.")), L.text(new TextAttr().lineHeight("xs"), List.of("Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table."))))L.Column(new() { Gap = "m" }, [ L.Text(new() { LineHeight = 1.6 }, ["Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them."]), L.Text(new() { LineHeight = "xs" }, ["Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table."]),])L::column(new ColumnAttr(gap: 'm'), [ L::text(new TextAttr(lineHeight: 1.6), ['Open lines, a factor of 1.6: easier to read on a long paragraph, and it takes more room, so a page holds fewer of them.']), L::text(new TextAttr(lineHeight: 'xs'), ['Tight lines, the token xs, a factor of 1.0: the lines of this paragraph touch more closely, as in a dense table.']),])Data binding
Section titled “Data binding”<text data-value="customer.name">Fallback name</text>The content of the element is replaced by the bound value at render time. The literal content is what renders when no data is passed.