Pretext: DOM-Free Text Measurement for JS

What is Pretext?

Pretext is a TypeScript library that measures and lays out multiline text without touching the DOM. A one-time prepare() pass segments the text and measures it with canvas measureText against the browser's own font engine; layout() then turns that into a height and line count with pure arithmetic — no getBoundingClientRect, no reflow.

Why avoid DOM text measurement?

Reading text height the normal way means calling getBoundingClientRect or offsetHeight, which forces the browser to run layout reflow — one of the more expensive things a browser does — every time you need a number for virtualization, an auto-growing textarea, or a resize handler. Pretext's own README frames this as the reason it exists: measure once with canvas against the real font engine, then treat every later width or resize as arithmetic instead of a fresh DOM read.

Core APIs: prepare, layout, and line walkers

• ✓prepare() runs the one-time work — normalize whitespace, segment the text, measure each piece with canvas — and returns an opaque handle you reuse.
• ✓layout() turns that handle into a height and line count with pure arithmetic, so it's cheap enough to call again on every resize.
• ✓prepareWithSegments() plus layoutWithLines() hands back the actual line strings, widths, and start/end cursors for manual rendering to canvas or SVG.
• ✓walkLineRanges() and measureLineStats() compute line count and max width without allocating any line text — handy for binary-searching a 'shrinkwrap' width.
• ✓layoutNextLineRange() streams one line at a time so the max width can change mid-paragraph, e.g. flowing text around a floated image.
• ✓A separate @chenglou/pretext/rich-inline entry point handles per-item fonts, atomic break: 'never' chips, and caller-owned extraWidth for pill chrome.
• ✓Soft hyphens inserted before prepare() become optional break points; a chosen break materializes as a trailing '-'.
• ✓setLocale() and clearCache() manage segmentation locale and shared caches for apps that cycle through many fonts.

Measuring text height without touching the DOM

Call prepare() once per text, font, and config, then reuse the result. It normalizes whitespace, segments the string, and measures each segment with canvas — the expensive work happens exactly once. Then call layout() on that handle whenever you need a height: ```ts import { prepare, layout } from '@chenglou/pretext' const prepared = prepare('Hello, world 你好', '16px Inter') const { height, lineCount } = layout(prepared, 320, 20) ``` layout() is cheap. Call it again on every resize — just don't call prepare() again for the same text and font, since that repeats the measurement pass. Pass { whiteSpace: 'pre-wrap' } to prepare() if you need textarea-style handling where spaces, tabs, and newlines stay visible. For manual line-by-line layout instead of just a height, swap in prepareWithSegments() and layoutWithLines(), which return the actual line strings and widths.

Installation

Install the package from npm: `npm install @chenglou/pretext`. That's the entire setup for using the library in your own app — no build step, config file, or bundler plugin is documented. If you want to see it work, the README describes a separate flow for running the bundled demos: clone the repo, run `bun install`, then `bun start` and open /demos/index in your browser (`bun run start:windows` on Windows). Prebuilt demos are also linked live from the README.

Alternatives to Pretext

Frequently asked questions

Best use cases

• •Sizing rows in a virtualized list or feed before they render, so scroll position doesn't jump when a guessed height turns out wrong.
• •Auto-growing textareas and chat composers that need pixel-accurate height as the user types, including preserved tabs and newlines via whiteSpace: 'pre-wrap'.
• •Dev-time or CI checks that a button or label won't overflow to a second line — no browser required to run the check.
• •Custom masonry-style or JS-driven layouts that need real paragraph line counts and widths instead of triggering CSS reflow to find out.
• •Flowing paragraph text around a floated image, where the available width per line shrinks until the image ends.
• •Shrinkwrapped UI like chat bubbles or tooltips that should size to the tightest width that still fits the text, via walkLineRanges().

Who should try it — and who should skip

Frontend engineers building virtualized lists, chat UIs, or auto-growing text inputs where a wrong pixel height causes layout shift are the target audience — especially if profiling already points at getBoundingClientRect as the hot path. Teams that need full CSS text rendering (variable font axes, font-feature-settings, RTL glyph-position accuracy) or that must run measurement in Node today should hold off; the README lists server-side as still coming, and several CSS features stay outside canvas's font shorthand.

Related repositories