@react-pdf/hyphenate

Fast Liang hyphenation with language scoped exports

Splits words into syllables using the TeX hyphenation patterns, with an entry point per language. Patterns are compiled into a trie once, so hyphenating a word costs a handful of short lookups rather than a scan of every pattern in the set.

Installation

yarn add @react-pdf/hyphenate

Usage

Import the language you need and hyphenate:

import { syllables, hyphenate } from '@react-pdf/hyphenate/en-us';

syllables('extraordinary'); // ['ex', 'tra', 'or', 'di', 'nary']
hyphenate('extraordinary'); // 'ex­tra­or­di­nary'

Each language is its own entry point, so bundlers only include the patterns you actually import:

import { syllables as syllablesDE } from '@react-pdf/hyphenate/de';
import { syllables as syllablesES } from '@react-pdf/hyphenate/es';

syllablesDE('Silbentrennung'); // ['Sil', 'ben', 'tren', 'nung']
syllablesES('caballero'); // ['ca', 'ba', 'lle', 'ro']

Results are cached per language, so repeated words are free.

Usage with react-pdf

Register a language other than the default en-us through Font.registerHyphenationCallback:

import { Font } from '@react-pdf/renderer';
import { syllables } from '@react-pdf/hyphenate/de';

Font.registerHyphenationCallback(syllables);

To disable hyphenation entirely, return the word untouched:

Font.registerHyphenationCallback((word) => [word]);

API Reference

syllables(word)

Splits a word into the syllables it may break into. Punctuation stays attached to the syllable it belongs to, and words shorter than five letters are returned whole.

import { syllables } from '@react-pdf/hyphenate/en-us';

syllables('something'); // ['some', 'thing']
syllables('something.'); // ['some', 'thing.']
syllables('cat'); // ['cat']

hyphenate(word)

Same as syllables, joined with soft hyphens (­).

import { hyphenate } from '@react-pdf/hyphenate/en-us';

hyphenate('something'); // 'some­thing'

patterns

The raw pattern set backing the language, should you need to pass it elsewhere.

import { patterns } from '@react-pdf/hyphenate/en-us';

createHyphenator(patterns)

Builds a hyphenator from any pattern set. The language entry points are thin wrappers around this.

import createHyphenator from '@react-pdf/hyphenate';
import patterns from 'hyphen/patterns/nl.js';

const { syllables, hyphenate } = createHyphenator(patterns);

Languages

Pattern data comes from hyphen, so every language it ships is available under the same name:

af as be bg bn ca cop cs cu cy da de de-1901 de-1996 de-ch-1901 el el-monoton el-polyton en en-gb en-us es et ethi eu fi fr fur ga gl grc gu hi hr hsb hu hy ia id is it ka kmr kn la la-x-classic la-x-liturgic lt lv ml mn mn-cyrl mn-cyrl-x-lmc mr mul-ethi nb nl nn no oc or pa pi pl pms pt rm ro ru sa sh sh-cyrl sh-latn sk sl sr sr-cyrl sv ta te th tk tr uk zh zh-latn-pinyin

Comparison

Measured on 20,000 unique English words from the system dictionary, so no library's cache ever hits and the numbers reflect matching alone. Each library ran in its own process, best of five. Sizes are for an en-us bundle, minified and gzipped with esbuild.

| Library | Matcher | With en-us patterns | Per word | | -------------------------- | ------- | --------------------- | -------- | | @react-pdf/hyphenate | 0.9 KB | 19.4 KB | 0.80 µs | | hypher 0.2.5 | 1.9 KB | 17.4 KB | 1.08 µs | | hyphenated 1.2.0 | — | 22.4 KB | 3.36 µs | | @lunarisapp/hyphen 1.2.1 | — | see below | 3.46 µs | | hyphen 1.6.4 | 2.0 KB | 20.2 KB | 70.77 µs |

hypher is the closest comparison: about a third slower per word, though it ships fewer bytes because its pattern data is more compact — 15.5 KB against 18.3 KB gzipped. The matcher itself is less than half the size of any other in the group.

@lunarisapp/hyphen exposes every language through a single entry point rather than per-language subpaths, so an en-us bundle measured 2 MB gzipped with all dictionaries included. That is not comparable to the other rows and is left out of the table.

hyphenopoly 6.1.0 is not listed. It compiles patterns to WebAssembly (20.5 KB for en-us, plus a loader) and sets up asynchronously, making it a different shape of tool rather than a faster or slower one.

License

MIT