Skip to content

Add lineBreak: 'whitespace' to wrap lines only at spaces - #1814

Merged
blikblum merged 1 commit into
foliojs:masterfrom
asmyshlyaev177:lineBreak-whitespace
Oct 10, 2026
Merged

blikblum merged 1 commit into
foliojs:masterfrom
asmyshlyaev177:lineBreak-whitespace

Conversation

@asmyshlyaev177

Copy link
Copy Markdown
Contributor

What kind of change does this PR introduce?

A feature. It adds a new value for the existing lineBreak option.

pdfkit can break a line after a hyphen or a slash, not just at a space. That's correct by the Unicode line breaking rules, but it splits words and links that should stay whole. A tool that reads text back out of the PDF then gets them wrong. Résumé parsers, search, and copy and paste all do this.

Example 1: a hyphenated word

doc.text('a design-system', { width });
Line 1 Line 2 A parser reads
Before a design- system designsystem
After, with lineBreak: 'whitespace' a design-system design-system

Example 2: a URL

doc.text('see https://github.com/foliojs/pdfkit', { width });
Line 1 Line 2 A parser reads
Before see https://github.com/foliojs/ pdfkit a link to https://github.com/foliojs/, then the word pdfkit
After, with lineBreak: 'whitespace' see https://github.com/foliojs/pdfkit the full link

There is no way around this in pdfkit today. The standard 14 fonts have no non-breaking hyphen (see #1040, where ‑ renders as blank space), and lineBreak: false means writing your own line wrapping.

What the option does

With lineBreak: 'whitespace', a line breaks only at:

  • a space or other whitespace
  • a newline
  • a soft hyphen (­), which still shows a hyphen at the line end
  • a zero-width space (​)

A word longer than the whole line is still split where the line ends, as it is today. The default behavior doesn't change. The option also works on a continued segment.

The option's type becomes boolean | 'whitespace'. If this PR is accepted, I'll update @types/pdfkit to match.

This PR doesn't fix #956, where the boundary between two continued segments is always a break point.

Checklist:

  • Unit Tests: the default rules as they are today, both examples above, soft hyphen, zero-width space, newline, a word wider than the line, and a continued segment
  • Documentation: docs/text.md
  • Update CHANGELOG.md
  • Ready to be merged

@blikblum
blikblum merged commit 0a254b6 into foliojs:master Oct 10, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Continued option breaks the word when it overflows the line

2 participants