High-Performance Text Wrapping for Virtualized UIs – uWrap

Preview:

Description:

uWrap is a JavaScript utility that predicts text wrapping behavior for virtualized lists and grids with exceptional speed and accuracy.

If you’ve ever built virtualized lists or grids displaying variable amounts of text, you know the headache: accurately and quickly estimating row heights BEFORE rendering is crucial for smooth scrolling.

DOM measurement is too slow, and the Canvas measureText() API, while faster, doesn’t handle wrapping natively and repeated calls add up quickly. This is exactly the problem uWrap tackles.

It accounts for various factors affecting text wrapping, including font size, variable-width kerning, letter spacing, explicit line breaks, and different white-space handling strategies.

Features:

• Blazing Fast: Significantly outperforms alternatives like canvas-hypertxt in benchmarks (often 10x+ faster).
• Lightweight: Less than 2KB minified, adding minimal overhead to your project.
• Simple API: Initialize once with a Canvas context, then use the returned count, test, and split functions.

Use Cases:

• Virtual Lists with Variable Height Rows: When implementing virtualized lists where each item contains different amounts of text, uWrap can predict row heights accurately without rendering DOM elements, enabling smooth scrolling experiences even with thousands of items.
• Dynamic Grid Layouts: For applications with card-based interfaces where text content needs to flow into containers of different widths, uWrap helps determine optimal layout dimensions before actual rendering.
• Text-Heavy Data Visualization: When building dashboards or reports with text components that need to fit specific dimensions, uWrap provides quick calculations for determining if text will overflow or how many lines it will occupy.
• Real-time Text Editors: For applications that need to predict text layout during typing or formatting changes, uWrap offers the performance needed for real-time feedback without UI jank.

How to use it:

1. Install uWrap using npm or load it directly into your HTML.

# NPM
$ npm install uwrap

import { varPreLine } from 'uwrap';

<!-- OR -->
<script src="./dist/uWrap.iife.min.js"></script>

2. Create a Canvas2D context (doesn’t need to be added to DOM).

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');

3. Configure the context font properties EXACTLY as your target elements.

ctx.font = "16px 'Roboto', sans-serif"; // Size, family
ctx.letterSpacing = '0.5px'; // Optional letter spacing
// ctx.wordSpacing = '2px'; // Optional word spacing

4. Initialize uWrap for variable-width fonts using the ‘pre-line’ strategy. This returns specialized functions for THIS context configuration.

const { count, test, split } = varPreLine(ctx);

5. Use the returned functions.

const text = "This is a longer piece of text that will likely need to wrap within a certain width.";
const maxWidth = 150; // Max width in pixels

6. Count the number of lines the text will occupy.

const lineCount = count(text, maxWidth);
console.log(`Lines needed: ${lineCount}`); // e.g., Lines needed: 3

7. Check if the text will wrap at all. This is faster than count if you only need a boolean check.

const willWrap = test(text, maxWidth);
console.log(`Will it wrap? ${willWrap}`); // e.g., Will it wrap? true

8. Get an array of the wrapped lines (optional line limit).

const maxLines = 5;
const linesArray = split(text, maxWidth, maxLines);
console.log('Split lines:', linesArray);
// e.g., Split lines: [ 'This is a longer', 'piece of text that', 'will likely need to', 'wrap within a', 'certain width.' ]

9. If you change font settings later, you need to re-initialize.

ctx.font = "12px Arial";
ctx.letterSpacing = '0px';
const { count: countSmall, split: splitSmall } = varPreLine(ctx);
const smallLines = countSmall(text, maxWidth);
console.log(`Lines needed (small): ${smallLines}`);

How It Works:

uWrap calculates text wrapping by precomputing character widths and kerning data from the Canvas2D context.

It creates a look-up table (LUT) for single-character metrics and measures pairs of characters for accurate spacing.

The implementation avoids expensive DOM reflows and the overhead of repeated measureText() calls.

It cycles through the text while maintaining pointers to potential wrap points and calculates cumulative widths until a line break is needed.

Internally, uWrap uses a custom iteration over characters and handles edge cases like multiple spaces, explicit newlines, and punctuation.

It accounts for letter-spacing nuances by detecting browser support, supplementing missing measurements with manual calculations when necessary.

This low-level approach ensures both speed and precision in scenarios where UI performance is critical.

FAQs

Q: Does uWrap work with all languages and character sets?
A: Currently, uWrap works most accurately with Latin charsets.

Q: How does uWrap handle RTL languages?
A: The current implementation doesn’t have specific optimizations for RTL text.

Q: How accurate is uWrap compared to actual browser text rendering?
A: uWrap is highly accurate for most Latin text scenarios. The main limitations involve complex text layouts, certain ligatures, and some edge cases with font rendering.

Q: Does uWrap support different white-space CSS properties?
A: Currently, only the pre-line wrapping strategy is implemented. Support for other white-space values is planned for future releases.

Q: How does uWrap handle explicit line breaks?
A: uWrap properly handles Unix-style \n line breaks. Windows-style \r\n breaks are not yet supported but are planned for future updates.