Skip to main content
prepare() is the one-time measurement pass. It normalizes whitespace, segments the text via Intl.Segmenter, measures each segment with canvas measureText, and caches the widths. The result is an opaque handle you pass to layout(). 
import { prepare, layout } from '@chenglou/pretext'

const prepared = prepare('AGI 春天到了. بدأت الرحلة 🚀', '16px Inter')
const { height, lineCount } = layout(prepared, containerWidth, 20)

​
Signature

prepare(text: string, font: string, options?: PrepareOptions): PreparedText

​
Parameters

​
text
string
required
The text string to measure. Whitespace is normalized according to the whiteSpace option (defaults to CSS white-space: normal behavior — collapsible spaces, no preserved newlines).
​
font
string
required
CSS font shorthand in the same format as canvasContext.font. Must exactly match your CSS font declaration for the element being measured — including size, weight, style, and family.Examples: "16px Inter", "bold 14px Arial", "italic 500 18px \"Helvetica Neue\"".
​
options
PrepareOptions
Optional configuration object.

​
Returns

​
PreparedText
object
An opaque handle. Do not inspect its contents — pass it directly to layout(). The handle is width-independent: the same PreparedText can be laid out at any maxWidth and lineHeight without re-preparing.

​
Performance

On the current benchmark snapshot, prepare() takes approximately 19ms for a batch of 500 texts. Call it once when a text block first appears (e.g. when a comment loads), then call layout() on every resize.
Avoid calling prepare() on every resize or render. The canvas measurement phase is expensive relative to layout(). Prepare once, lay out many times.

​
Whitespace modes

For standard paragraph text, the default 'normal' mode is correct. For textarea content where newlines and tabs must be preserved, pass { whiteSpace: 'pre-wrap' }: 
const prepared = prepare(textareaValue, '16px Inter', { whiteSpace: 'pre-wrap' })
const { height } = layout(prepared, textareaWidth, 20)

​
Font accuracy note

Avoid system-ui as the font on macOS. The canvas context and the DOM can resolve system-ui to different optical variants, causing measurement drift. Use a named font such as "Helvetica", "Inter", or "Arial" for guaranteed accuracy.
The font string must be an exact match for the CSS font shorthand on the measured element. A mismatch in weight, size, or family will produce incorrect widths.

Build docs developers (and LLMs) love

Get started for freeTalk to us