pretext

name	pretext
description	Fast, accurate, and comprehensive multiline text measurement and layout library for JavaScript/TypeScript — without DOM reflow. Use when the user needs to calculate paragraph heights, line counts, manual line layouts (text flowing around floated images), or rich text rendering (emoji, CJK, RTL) on DOM, Canvas, or SVG targets. Covers npm install, core API (prepare/layout, prepareWithSegments/layoutWithLines), and options (whiteSpace, wordBreak, letterSpacing). Triggers on: pretext, text measurement, text layout, paragraph height, line layout, text reflow, canvas text measurement, DOM reflow.
allowed-tools	Read Write Bash Grep Glob WebFetch
metadata	{"tags":"pretext, text-measurement, text-layout, typography, canvas, dom, svg, reflow, multiline, cjk, emoji, rich-text, javascript, typescript","platforms":"Claude Code, Codex CLI, Gemini CLI, OpenCode","keyword":"pretext","version":"latest","source":"chenglou/pretext","license":"MIT"}

pretext — Fast Multiline Text Measurement & Layout

No DOM reflow. Pure arithmetic on cached font metrics.

pretext is a pure JavaScript/TypeScript library for fast, accurate, and comprehensive multiline text measurement and layout — without triggering getBoundingClientRect, offsetHeight, or any other DOM reflow operations.

Installation

Plugin (Claude Code)

claude plugin marketplace add chenglou/pretext

npm

npm install @chenglou/pretext

Skill (any platform)

npx skills add https://github.com/akillness/jeo-skills --skill pretext

When to use

• Calculate paragraph heights and line counts without measuring in the DOM
• Build manual line layouts for text flowing around floated images or variable-width containers
• Handle rich text with emoji, CJK characters, RTL text, and mixed-language content
• Render measured text to DOM, Canvas, or SVG with accurate metrics
• Implement soft hyphenation, letter-spacing, or locale-aware word breaking
• Avoid layout reflow in performance-critical rendering loops
• Server-side text measurement (SSR-friendly)

Do not use when

• You need full CSS text engine fidelity → rely on DOM measurements directly
• You need OpenType feature support (ligatures, kerning tables) → use a dedicated font shaping library
• You need PDF text layout → route to a PDF generation library
• Your target environment lacks Intl.Segmenter and Canvas 2D support

Core API

Use Case 1: Height Measurement

Calculate paragraph height and line count with pure arithmetic — no DOM touch after prepare().

import { prepare, layout } from '@chenglou/pretext'

// One-time analysis + font measurement (cached)
const prepared = prepare('AGI 春天到了. بدأت الرحلة 🚀‎', '16px Inter')

// Pure arithmetic — no DOM interaction
const { height, lineCount } = layout(prepared, 320, 20)
// width: 320px container, lineHeight: 20px

Use Case 2: Manual Line Layout

Access individual lines for custom rendering (e.g., text around floated images).

import { prepareWithSegments, layoutWithLines } from '@chenglou/pretext'

const prepared = prepareWithSegments('Text here', '18px "Helvetica Neue"')
const { lines } = layoutWithLines(prepared, 320, 26)

for (const line of lines) {
  // line.text, line.y, line.width, line.segments
}

Use Case 3: Shrink-wrap width

Find the minimum container width that fits the text without wrapping.

import { prepare, shrinkWrap } from '@chenglou/pretext'

const prepared = prepare('Hello world', '14px system-ui')
const { width } = shrinkWrap(prepared, 26)

Options reference

Option	Type	Values	Description
whiteSpace	string	'normal' | 'pre-wrap'	'pre-wrap' preserves whitespace (textarea-style)
wordBreak	string	'normal' | 'keep-all'	'keep-all' prevents mid-word breaks in CJK text
letterSpacing	number	pixels	CSS-equivalent letter-spacing

const prepared = prepare(text, font, {
  whiteSpace: 'pre-wrap',
  wordBreak: 'keep-all',
  letterSpacing: 1.5,
})

Requirements

• Intl.Segmenter API (locale-aware word/grapheme segmentation)
• Canvas 2D text measurement (CanvasRenderingContext2D.measureText)
• Works in modern browsers and Node.js 16+ (with canvas package for Node)

Output targets

Target	Notes
DOM	Use lines + absolute positioning or transform: translateY
Canvas	Use lines[i].y + ctx.fillText
SVG	Use lines[i].y + <text y=...> elements
SSR	Heights computed server-side; hydrate positions client-side

Operating rules

1. Call prepare() / prepareWithSegments() once per unique (text, font) pair — it's the expensive step
2. Cache prepared objects when the same text is measured at different widths
3. Call layout() / layoutWithLines() freely — it's pure arithmetic with no side effects
4. Always check Intl.Segmenter availability before initializing in non-browser environments
5. Use shrinkWrap to find minimum width before measuring at a fixed container width
6. Prefer prepareWithSegments over prepare when you need per-line segment access for rich rendering

Examples

import { prepare, layout, prepareWithSegments, layoutWithLines } from '@chenglou/pretext'

// Basic height check
const p = prepare('Hello, 世界! 🌏', '16px sans-serif')
console.log(layout(p, 200, 20))  // { height: 20, lineCount: 1 }

// Variable-width layout (text around floated image)
const ps = prepareWithSegments('Long article text...', '16px Georgia')
const { lines } = layoutWithLines(ps, (lineIndex) => {
  return lineIndex < 5 ? 200 : 320  // narrower for first 5 lines
}, 24)

Source: chenglou/pretext — MIT License