Pretext: High-Performance Text Measurement

Introduction

Pretext is a TypeScript library that enables high-performance text measurement by bypassing expensive browser layout reflows. It allows developers to calculate text dimensions and line breaks in memory, which is essential for building complex, performant UI components like virtualized lists or masonry layouts.

Configuration Checklist

Element	Version / Link
Language / Runtime	TypeScript / Node.js
Main library	@chenglou/pretext
Required APIs	Canvas API (CanvasRenderingContext2D)
Keys / credentials needed	None

Step 1 — Preparing Text Segments

Preparing text is the initial step to break down strings into segments and cache their pixel widths. This avoids repeated calls to the DOM during the layout phase.

import { prepare } from '@chenglou/pretext';

// Analyze font once to cache segment widths (1-5ms execution time)
const prepared = await prepare('Hello, 世界 🌍', '16px Inter');

Step 2 — Calculating Layout

Once the text is prepared, you can calculate the total height and line count at any given width without triggering a browser reflow.

import { layout } from '@chenglou/pretext';

// Calculate layout at a specific width (0.0002ms execution time)
const { height, lineCount } = layout(prepared, 300);

console.log(height);    // Exact pixel height
console.log(lineCount); // Number of lines

Comparison Tables

Metric	Standard DOM Measurement	Pretext
Performance	High (Triggers Reflow)	Low (No Reflow)
Complexity	High (Requires DOM nodes)	Low (In-memory)
Use Case	Simple static text	Virtualized lists, complex UI

⚠️ Common Mistakes & Pitfalls

1. Forcing Reflows: Using getBoundingClientRect() or offsetWidth inside a loop causes layout thrashing. Fix: Use Pretext to calculate dimensions in memory before rendering.
2. Ignoring Font Context: Measuring text without specifying the correct font family and size leads to inaccurate results. Fix: Ensure the prepare() function receives the exact font string used in your CSS.
3. Over-rendering: Rendering all items in a long list instead of using a virtualized approach. Fix: Use Pretext to calculate the height of hidden items to maintain a correct scrollbar size without rendering them.

Glossary

Layout Reflow: The process where the browser recalculates the position and geometry of elements on a page, which is computationally expensive.
Virtualized List: A UI pattern where only the items currently visible to the user are rendered in the DOM to improve performance.
Canvas API: A low-level browser API used for drawing graphics and measuring text outside of the standard DOM flow.

Key Takeaways

• Pretext eliminates the performance cost of layout reflows for text-heavy applications.
• The library uses the Canvas API to measure text widths in memory.
• It provides a two-step API: prepare() for caching and layout() for calculation.
• It is ideal for complex UI components like virtualized lists and masonry layouts.
• By bypassing the DOM, it enables 60fps performance for dynamic text interfaces.

Resources

• Pretext GitHub Repository
• Pretext Demos