The text layout primitive React Native was missing. Native measurement, ~0.0002ms pure-JS layout arithmetic, and full control over how text flows — around shapes, inside gestures, through animations. All with regular <View> and <Text>. No Skia canvas, no SVG tricks.
v1.0.0 is here. Production-ready. Closes 18+ open React Native text bugs — Android cut-off clusters, italic clipping, numberOfLines edge cases, font-load races, silent font fallback, and CJK typography.
Flexbox is rectangular boxes all the way down. iOS TextKit has NSTextContainer.exclusionPaths. CSS has shape-outside. The native capability exists on every platform — React Native just never exposed it. Even react-native-skia's Paragraph API is rectangle-only (open issue since 2022).
expo-pretext closes that gap:
- Text reflow around arbitrary shapes — circles, rectangles, or any polygon. Magazine-style layouts, circular avatars with wrapping captions, text that reacts to moving obstacles.
- Exact heights before render — FlashList virtualization with zero
onLayoutjumps, even for 10k messages with rich markdown. - Per-frame layout recomputation —
layout()runs in ~0.0002ms, fast enough to run 120+ times per frame during gestures, physics, or animations. - Streaming AI chat — cache-aware incremental measurement for token-by-token reveals.
- Regular RN rendering tree — A11y, Dynamic Type, selection, copy/paste, VoiceOver, RTL, emoji ZWJ — all work, because you're still using
<Text>.
prepare(text, style) One native measurement call per text
→ Native: iOS TextKit / Android TextPaint / Web Canvas
→ Returns: cached segment widths + break opportunities
→ Time: ~15ms for 500 texts in a batch
layout(prepared, maxWidth) Pure JS arithmetic on cached data
→ No native bridge, no DOM, no reflow
→ Time: ~0.0002ms per text
→ Safe to call 120+ times per frame
The flagship demo is a Breakout arcade game where the live prose background reflows around the ball, the paddle, and every falling brick at 60fps. It exists to prove the performance claim visually, not just in a benchmark.
npx expo install expo-pretextRequires Expo SDK 52+, React Native 0.76+, New Architecture / Fabric. Reanimated is an optional peer dependency used only by the animation hooks. Expo Go falls back to JS estimates — use a development build for native measurement.
import { useTextHeight } from 'expo-pretext'
function ChatBubble({ text, maxWidth }) {
const height = useTextHeight(text, {
fontFamily: 'Inter',
fontSize: 16,
lineHeight: 24,
}, maxWidth)
return <View style={{ height }}><Text>{text}</Text></View>
}useFlashListHeights pre-warms a height cache in the background and returns
getHeight(item) — set it as an explicit height on the wrapping View inside
renderItem. FlashList v2 skips the measurement pass when the height is known,
eliminating first-paint jitter for plain-text lists.
import { useFlashListHeights } from 'expo-pretext'
import { FlashList } from '@shopify/flash-list'
import { View, Text } from 'react-native'
const STYLE = { fontFamily: 'Inter', fontSize: 16, lineHeight: 24 }
const PAD_Y = 10
function ChatScreen({ messages, width }) {
const { getHeight } = useFlashListHeights(
messages,
msg => msg.text,
STYLE,
width,
)
return (
<FlashList
data={messages}
keyExtractor={m => m.id}
renderItem={({ item }) => (
<View style={{ height: getHeight(item) + PAD_Y * 2 }}>
<Text style={STYLE}>{item.text}</Text>
</View>
)}
/>
)
}For plain
<Text>content,getHeight(item)returns the exact rendered height (FlashList v2 no longer acceptsestimatedItemSizeor a size-bearingoverrideItemLayout). For rich content like Markdown or mixed components, let FlashList v2 auto-measure instead.
import { useObstacleLayout } from 'expo-pretext'
function MagazineLayout({ text, width }) {
const layout = useObstacleLayout(
text,
{ fontFamily: 'Georgia', fontSize: 18, lineHeight: 28 },
{ x: 0, y: 0, width, height: 600 },
// circular avatar to flow around
[{ cx: 80, cy: 80, r: 64 }],
)
return (
<View style={{ height: layout.height }}>
{layout.lines.map((line, i) => (
<Text key={i} style={{ position: 'absolute', left: line.x, top: line.y }}>
{line.text}
</Text>
))}
<Image source={avatar} style={{ position: 'absolute', width: 128, height: 128, borderRadius: 64 }} />
</View>
)
}import { useStreamingLayout } from 'expo-pretext'
function StreamingBubble({ text, maxWidth }) {
// Auto-detects append pattern. Cache-aware. ~2ms per token.
const { height, lineCount, doesNextTokenWrap } = useStreamingLayout(text, style, maxWidth)
return (
<View style={{ minHeight: height }}>
<Text>{text}</Text>
</View>
)
}import { usePinchToZoomText } from 'expo-pretext/animated'
import Animated from 'react-native-reanimated'
function ZoomableText({ text, maxWidth }) {
const zoom = usePinchToZoomText(text, baseStyle, maxWidth, {
minFontSize: 8,
maxFontSize: 48,
})
// layout() runs per frame. 120+ recalculations/frame possible.
return <Animated.Text style={[baseStyle, zoom.animatedStyle]}>{text}</Animated.Text>
}Since RN 0.78, Android's text renderer has regressed in several ways: descender clipping, text disappearing under certain font weights, extra wraps from letterSpacing. <SafeText> computes line breaks ourselves and emits one <Text> per line — RN has no wrap decision left to make, and cut-off goes away.
import { SafeText } from 'expo-pretext'
<SafeText
style={{ fontFamily: 'Inter', fontSize: 16, lineHeight: 24 }}
maxWidth={containerWidth}
>
{paragraphText}
</SafeText>Closes RN #15114, #49886, #53286, #53666, #56402, #48921.
numberOfLines + ellipsizeMode has long-standing issues: Android's middle / head modes break for multi-line; iOS drops the ellipsis when the source has \n; the ellipsis inherits the trimmed text's background color. <TruncatedText> computes the visible substring in JS and renders it as plain text.
import { TruncatedText } from 'expo-pretext'
<TruncatedText
style={{ fontFamily: 'Inter', fontSize: 14 }}
maxWidth={containerWidth}
maxLines={3}
mode="tail" // or 'head' / 'middle'
>
{longArticleText}
</TruncatedText>Closes RN #19117, #41405, #37926.
Call enableAutoInvalidation() once at app root; caches clear automatically on system font-scale changes and on expo-font load events.
import { enableAutoInvalidation, notifyFontsLoaded } from 'expo-pretext'
import { useFonts } from 'expo-font'
export default function App() {
const [loaded] = useFonts({ Inter: require('./Inter.ttf') })
useEffect(() => {
const stop = enableAutoInvalidation()
return stop
}, [])
useEffect(() => {
if (loaded) notifyFontsLoaded()
}, [loaded])
// …
}Addresses Expo #21885 (82 comments on useFonts reliability).
Custom fonts sometimes report as loaded but fall back to System. verifyFontsLoaded() measures a reference string with the requested font vs System and reports whether the custom font is actually applied.
import { verifyFontsLoaded } from 'expo-pretext'
const v = verifyFontsLoaded({ fontFamily: 'Inter', fontSize: 16 })
if (v && !v.applied) {
console.warn('Inter is not being applied — falling back to System')
}Closes RN #54934, #56309, #54642.
For react-native-skia users who need precise glyph bounds with font fallback resolved in JS (Skia #3493, #3488, #1736).
import { measureRuns } from 'expo-pretext'
const { naturalWidth, naturalHeight, runs } = measureRuns('Hello', style)
// runs: Array<{ text, bounds, advance, font: { family, size, weight, style } }>Pure measurement — doesn't require react-native-skia installed.
React Native sizes text containers to advance width, but italic glyphs extend beyond that — causing visual clipping. expo-pretext fixes this with ink-bounds measurement.
Drop-in fix — one component:
import { InkSafeText } from 'expo-pretext'
// Before (clips): <Text style={style}>fly</Text>
// After (fixed):
<InkSafeText style={{
fontFamily: 'Georgia',
fontSize: 80,
fontWeight: 'bold',
fontStyle: 'italic',
}}>
fly
</InkSafeText><InkSafeText> is a drop-in <Text> replacement. Non-italic text renders with zero overhead.
Custom container sizing — hook:
import { useInkSafeStyle } from 'expo-pretext'
const { style: safeStyle, inkWidth } = useInkSafeStyle(text, baseStyle)
<View style={{ width: inkWidth, overflow: 'hidden' }}>
<Text style={safeStyle} numberOfLines={1}>{text}</Text>
</View>FlashList / imperative — pure function:
import { getInkSafePadding } from 'expo-pretext'
const { padding, inkWidth } = getInkSafePadding(text, style)| Category | What you get |
|---|---|
| Drop-in components | <SafeText>, <TruncatedText>, <InkSafeText> |
| Layout primitives | layoutColumn (obstacles), useObstacleLayout, fitFontSize, truncateText, customBreakRules, measureNaturalWidth, measureInkWidth (italic-safe) |
| Virtualization | useTextHeight, useFlashListHeights, measureHeights (batch) |
| Streaming AI chat | useStreamingLayout, useMultiStreamLayout, prepareStreaming, measureCodeBlockHeight |
| Animation (Reanimated) | useAnimatedTextHeight, useCollapsibleHeight, usePinchToZoomText, useTypewriterLayout, useTextMorphing |
| Rich inline flow | prepareInlineFlow, walkInlineFlowLines, measureInlineFlow — mixed fonts, @mentions, pills |
| Accessibility | getFontScale, onFontScaleChange, clearAllCaches, enableAutoInvalidation, notifyFontsLoaded |
| Cross-platform consistency | ENGINE_PROFILES, setEngineProfile, getEngineProfile — iOS ≡ Android ≡ Web |
| Font metrics + fallback | getFontMetrics, resolveFontFamily, validateFont, verifyFontsLoaded |
| Hyphenation | compileHyphenationPatterns, hyphenate, hyphenateAndJoin (Liang-Knuth; bring your own TeX patterns) |
| Skia adapter | measureRuns — per-run bounds + advance + font for Skia Paragraph |
| Developer tools | <PretextDebugOverlay>, compareDebugMeasurement, buildHeightSnapshot, compareHeightSnapshots, prepareWithBudget, PrepareBudgetTracker |
| Power API | prepare, layout, layoutWithLines, layoutNextLine, walkLineRanges, prepareWithSegments |
See src/index.ts for the full public surface.
| # | Feature | Closes |
|---|---|---|
| 1 | letterSpacing support |
RN #54823, #46436 |
| 2 | Auto cache invalidation | Expo #21885 (82 comments) |
| 3 | <InkSafeText strict> |
RN #49886, #53286, #56402, #15114 |
| 4 | <TruncatedText> |
RN #19117, #41405, #37926 |
| 5 | <SafeText> (flagship) |
RN #15114, #49886, #53286, #53666, #56402, #48921 |
| 6 | Kinsoku Shori (CJK) | Japanese / Chinese line-break correctness |
| 7 | verifyFontsLoaded() |
RN #54934, #56309, #54642 |
| 8 | measureRuns() Skia adapter |
Skia #3493, #3488, #1736 |
Full Unicode via native OS segmenters. No locale hacks, no userland Intl polyfills, no manual script detection:
- CJK (Chinese, Japanese, Korean) — per-character breaking with Kinsoku Shori (
、。）」never start a line;（「『never end one) — locked in with 13 targeted tests - Arabic, Hebrew — RTL with bidi metadata; full UBA rules covered by 30 tests
- Thai, Lao, Khmer, Myanmar — dictionary-based word boundaries
- Georgian, Devanagari, Armenian, Ethiopic — all native scripts
- Emoji — compound graphemes, flag sequences, ZWJ family joiners
- Mixed scripts in a single string, measured correctly
- Hyphenation (Liang-Knuth) — user-supplied TeX patterns, any language
| Operation | Cost |
|---|---|
prepare() batch |
~15ms for 500 texts |
layout() per call |
~0.0002ms (pure arithmetic) |
| Streaming token | ~2ms (mostly cache hits) |
| Native cache | LRU 5000 segments/font, frequency-based eviction |
| JS cache | Skip native calls entirely when all segments are cached |
expo-pretext uses native platform text measurement — the same engines that render your text. Two modes:
fast(default): sum individual segment widths. Sub-pixel kerning differences absorbed by tolerance.exact: re-measure merged segments. Pixel-perfect at the cost of one extra native call.
Cross-platform drift between iOS, Android, and Web is bounded by ENGINE_PROFILES — use consistent mode when you need identical layouts across all three.
| Platform | Backend | Status |
|---|---|---|
| iOS | TextKit (NSLayoutManager, NSAttributedString, CFStringTokenizer) |
New Architecture / Fabric verified |
| Android | TextPaint, BreakIterator, Paint.FontMetrics |
Kotlin native module |
| Expo Web | CanvasRenderingContext2D.measureText + Intl.Segmenter |
Zero API changes |
| Expo Go | JS estimates (no native measurement) | Use a dev build for production |
Verified against FlashList 2.3.1, React Native 0.83, Expo SDK 55.
expo-pretext is a React Native / Expo / Web port of Pretext by Cheng Lou. The core line-breaking algorithm is ported; the measurement backends are new (iOS TextKit, Android TextPaint, Web Canvas instead of DOM APIs). Pretext itself builds on Sebastian Markbage's text-layout research.
MIT