packages/textkit/README.md
An advanced text layout framework
A comprehensive text layout engine for react-pdf. Handles complex text rendering including bidirectional text, line breaking, hyphenation, justification, font substitution, and text decoration.
This project is a fork of textkit by @devongovett and continued under the scope of this project since it has react-pdf specific features. Any recongnition should go to him and the original project mantainers.
yarn add @react-pdf/textkit
import layoutEngine, {
bidi,
linebreaker,
justification,
textDecoration,
scriptItemizer,
wordHyphenation,
fontSubstitution,
fromFragments,
} from '@react-pdf/textkit';
// Create engines configuration
const engines = {
bidi: bidi(),
linebreaker: linebreaker({}),
justification: justification({}),
textDecoration: textDecoration(),
scriptItemizer: scriptItemizer(),
wordHyphenation: wordHyphenation(),
fontSubstitution: fontSubstitution(),
};
// Create attributed string from fragments
const attributedString = fromFragments([
{ string: 'Hello ', attributes: { fontSize: 12, font: [myFont] } },
{ string: 'World!', attributes: { fontSize: 12, font: [myFont] } },
]);
// Define container
const container = {
x: 0,
y: 0,
width: 400,
height: 600,
};
// Layout text
const layout = layoutEngine(engines);
const paragraphs = layout(attributedString, container, {});
The layout engine processes text through the following steps:
The layout engine uses several specialized engines that can be customized:
Handles bidirectional text analysis using the Unicode Bidirectional Algorithm. Determines text direction for mixed LTR/RTL content.
import { bidi } from '@react-pdf/textkit';
const bidiEngine = bidi();
const result = bidiEngine(attributedString);
Performs line breaking using the Knuth-Plass algorithm with fallback to best-fit. Handles hyphenation points and produces optimal line breaks.
import { linebreaker } from '@react-pdf/textkit';
const linebreakerEngine = linebreaker({
tolerance: 4,
hyphenationPenalty: 100,
});
Adjusts character and word spacing to achieve justified text alignment. Based on Apple's justification algorithm.
import { justification } from '@react-pdf/textkit';
const justificationEngine = justification({
expandCharFactor: { before: 0, after: 0 },
shrinkCharFactor: { before: 0, after: 0 },
expandWhitespaceFactor: { before: 0.5, after: 0.5 },
shrinkWhitespaceFactor: { before: 0.5, after: 0.5 },
});
Automatically substitutes fonts when the primary font doesn't have glyphs for certain characters. Picks the best font from the font stack.
import { fontSubstitution } from '@react-pdf/textkit';
const fontSubstitutionEngine = fontSubstitution();
Identifies Unicode script runs in text (Latin, Arabic, Han, etc.) to enable proper font selection and shaping.
import { scriptItemizer } from '@react-pdf/textkit';
const scriptItemizerEngine = scriptItemizer();
Provides word hyphenation using language-specific patterns. Supports soft hyphens and custom hyphenation callbacks.
import { wordHyphenation } from '@react-pdf/textkit';
const wordHyphenationEngine = wordHyphenation();
const syllables = wordHyphenationEngine('hyphenation'); // ['hy', 'phen', 'a', 'tion']
Generates decoration lines (underline, strikethrough) for styled text runs.
import { textDecoration } from '@react-pdf/textkit';
const textDecorationEngine = textDecoration();
Creates a layout function with the specified engines.
const layout = layoutEngine(engines);
const paragraphs = layout(attributedString, container, options);
Creates an AttributedString from text fragments.
import { fromFragments } from '@react-pdf/textkit';
const attributedString = fromFragments([
{ string: 'Hello ', attributes: { fontSize: 14 } },
{ string: 'World!', attributes: { fontSize: 14, color: 'blue' } },
]);
The main data structure representing styled text:
type AttributedString = {
string: string;
runs: Run[];
syllables?: string[];
box?: Rect;
decorationLines?: DecorationLine[];
};
A styled segment of text:
type Run = {
start: number;
end: number;
attributes: Attributes;
glyphs?: Glyph[];
positions?: Position[];
glyphIndices?: number[];
};
Style attributes for text runs:
type Attributes = {
align?: string;
alignLastLine?: string;
attachment?: Attachment;
backgroundColor?: string;
bidiLevel?: number;
characterSpacing?: number;
color?: string;
direction?: 'rtl' | 'ltr';
features?: unknown[];
fill?: boolean;
font?: Font[];
fontSize?: number;
hangingPunctuation?: boolean;
hyphenationFactor?: number;
indent?: number;
justificationFactor?: number;
lineHeight?: number;
lineSpacing?: number;
link?: string;
margin?: number;
marginLeft?: number;
marginRight?: number;
opacity?: number;
padding?: number;
paddingTop?: number;
paragraphSpacing?: number;
scale?: number;
script?: unknown;
shrinkFactor?: number;
strike?: boolean;
strikeColor?: string;
strikeStyle?: string;
stroke?: boolean;
underline?: boolean;
underlineColor?: string;
underlineStyle?: string;
verticalAlign?: string;
wordSpacing?: number;
yOffset?: number;
};
The area where text will be laid out:
type Container = {
x: number;
y: number;
width: number;
height: number;
truncateMode?: 'ellipsis';
maxLines?: number;
excludeRects?: Rect[];
};
A rectangle definition:
type Rect = {
x: number;
y: number;
width: number;
height: number;
};
Input format for creating attributed strings:
type Fragment = {
string: string;
attributes?: Attributes;
};
Options for the layout process:
type LayoutOptions = {
hyphenationCallback?: (
word: string | null,
fallback: (word: string | null) => string[],
) => string[];
tolerance?: number;
hyphenationPenalty?: number;
expandCharFactor?: JustificationFactor;
shrinkCharFactor?: JustificationFactor;
expandWhitespaceFactor?: JustificationFactor;
shrinkWhitespaceFactor?: JustificationFactor;
};
The engines configuration object:
type Engines = {
bidi: ReturnType<typeof bidi>;
linebreaker: ReturnType<typeof linebreaker>;
justification: ReturnType<typeof justification>;
fontSubstitution: ReturnType<typeof fontSubstitution>;
scriptItemizer: ReturnType<typeof scriptItemizer>;
textDecoration: ReturnType<typeof textDecoration>;
wordHyphenation?: ReturnType<typeof wordHyphenation>;
};
MIT