react-pretext

React wrapper for @chenglou/pretext — fast multiline text measurement and layout without DOM reflow.

pretext separates text measurement into two phases:

• prepare(text, font) — segments and measures text using an off-screen canvas (~expensive, cached)
• layout(handle, width, lineHeight) — pure arithmetic, sub-millisecond per call

react-pretext wraps these phases behind a hook and a component, adds automatic width tracking via ResizeObserver, reads font properties from getComputedStyle when not provided explicitly, and caches prepare() handles in a global LRU cache.

Installation

npm install react-pretext @chenglou/pretext

Peer dependencies: react >= 17, react-dom >= 17, @chenglou/pretext

Quick start

Hook

import { useTextLayout } from 'react-pretext'

function MyComponent() {
  const { ref, height, lineCount } = useTextLayout('Hello world', {
    width: 320,
    fontSize: 16,
    fontFamily: 'Inter',
  })

  return (
    <div ref={ref as React.RefObject<HTMLDivElement>} style={{ width: 320, fontSize: 16 }}>
      Hello world
      <span>height: {height}px, lines: {lineCount}</span>
    </div>
  )
}

Component

import { PreText } from 'react-pretext'

function MyComponent() {
  return (
    <PreText
      fontSize={16}
      fontFamily="Inter"
      onLayout={({ height, lineCount }) => console.log(height, lineCount)}
    >
      Hello world
    </PreText>
  )
}

API

useTextLayout(text, options?)

function useTextLayout(text: string, options?: UseTextLayoutOptions): TextLayoutResult

Options

| Prop | Type | Default | Description | |---|---|---|---| | width | number | — | Container width in px. If omitted, tracked via ResizeObserver on the returned ref. | | lineHeight | number | fontSize * 1.2 | Line height in px. | | withLines | boolean | false | When true, populates lines via layoutWithLines(). | | fontSize | number | from getComputedStyle | | | fontFamily | string | from getComputedStyle | | | fontWeight | string \| number | from getComputedStyle | | | fontStyle | string | from getComputedStyle | | | cacheSize | number | 500 | Override global LRU max size. See configureCache() for deterministic control. |

Returns

| Field | Type | Description | |---|---|---| | ref | RefObject<HTMLElement> | Attach to the container element. Used for auto-width and font fallback. | | height | number \| null | null until first measurement (always null during SSR). | | lineCount | number \| null | null until first measurement. | | lines | LineInfo[] \| null | Populated only when withLines: true. |

<PreText>

All FontProps fields are available as props, plus width and lineHeight from UseTextLayoutOptions, plus:

| Prop | Type | Default | Description | |---|---|---|---| | children | string | required | The text to measure and render. | | renderLines | boolean | false | Render each line as an absolutely positioned <span>. Client-only — see SSR section. | | onLayout | (info: { height, lineCount, lines? }) => void | — | Called after each measurement update. | | as | keyof JSX.IntrinsicElements | "div" | HTML element to render as. |

All other HTML attributes are forwarded to the wrapper element.

configureCache(options)

configureCache({ maxSize: 1000 })

Sets the global LRU cache capacity. Call once at app startup for deterministic behaviour. The default capacity is 500 entries. Entries are keyed on text + fontString and evicted least-recently-used.

Types

type FontProps = {
  fontSize?: number
  fontFamily?: string
  fontWeight?: string | number
  fontStyle?: string
}

type LineInfo = {
  text: string
  width: number
  x: number
  y: number
}

Auto font detection

When FontProps fields are omitted, react-pretext reads them from getComputedStyle on the element attached to ref. This means you can style the element via CSS and skip passing font props entirely:

<PreText style={{ fontSize: '1rem', fontFamily: 'Inter' }} onLayout={console.log}>
  Hello world
</PreText>

If the element is not yet mounted (edge case on first render), the fallback is "normal normal 16px sans-serif".

SSR / Next.js

Default mode (renderLines={false}) — SSR safe

height and lineCount are null on the server. The component renders its children inside the wrapper element without layout data. No crash, no hydration mismatch. After hydration, the hook activates and onLayout fires with real values.

renderLines={true} — client-only

On the server there are no positioned <span> elements. After hydration, absolutely positioned spans appear. This causes a React hydration mismatch warning.

Next.js App Router — mark as client component:

// components/MyText.tsx
'use client'
import { PreText } from 'react-pretext'

export function MyText({ children }: { children: string }) {
  return <PreText renderLines fontSize={16} fontFamily="Inter">{children}</PreText>
}

Next.js Pages Router — use dynamic import:

import dynamic from 'next/dynamic'

const PreText = dynamic(
  () => import('react-pretext').then((m) => m.PreText),
  { ssr: false },
)

When renderLines={true} and height is not yet known (before the first client-side measurement), the wrapper has height: 0 and spans are not visible. This resolves after the first layout cycle on the client.

Demo

npm run demo

Opens a Vite dev server with five interactive examples:

1. Basic <PreText> with auto font detection
2. renderLines with custom line highlight
3. useTextLayout hook with a manual width slider
4. Live resize — drag the container edge to see layout update in real time
5. Cache behaviour — edit text to observe prepare() call counts

License

MIT