react-wrap-balancer

React Wrap Balancer is a lightweight React component that improves how multi-line text wraps by balancing line lengths, avoiding awkward situations like a single orphaned word dangling on the last line of a heading. It works by measuring the container synchronously via a binary-search algorithm and constraining the wrapper’s max-width so the browser reflows text into more evenly sized lines.

Built by Shu Ding (of Vercel/Next.js) and used widely across marketing sites and blogs, it supports SSR out of the box via an inlined relayout script, offers an opt-in <Provider> for sharing the relayout logic across many <Balancer> instances, and can defer to the native CSS text-wrap: balance property when the browser supports it.

What You Get

• The <Balancer> component that wraps any inline text or heading content and balances its line breaks automatically
• An optional <Provider> component for sharing the client-side relayout logic across multiple <Balancer> instances on a page
• SSR-safe rendering via an inlined <script> tag that runs the balancing calculation before hydration, avoiding layout shift
• Automatic fallback to native CSS text-wrap: balance in browsers that support it, skipping the JS relayout entirely via preferNative
• A configurable ratio prop (0-1) to tune how aggressively lines are balanced

Common Use Cases

• Balancing marketing and landing page headlines so they don’t end in a single orphaned word
• Making blog post and article titles read more evenly across different screen widths
• Improving card and product titles in grids where uneven line breaks look inconsistent

Under The Hood

Architecture - React Wrap Balancer’s core is a single relayout function (src/index.tsx) that runs a synchronous binary search against the container’s clientWidth/clientHeight to find the narrowest wrapper width that doesn’t add an extra line, then pins the wrapper’s max-width to that value. The function is serialized with .toString() and inlined into a <script> tag so it can run during SSR/hydration before React attaches, avoiding a flash of unbalanced text; each <Balancer> also registers a ResizeObserver on its parent container so the layout is recalculated when the container resizes.

Tech Stack - The library is nearly pure TypeScript/TSX with a single production-dependency-free src/index.tsx (316 lines) and a small src/utils.tsx helper providing useId/useIsomorphicLayoutEffect polyfills that keep it compatible back to React 16.8. It’s built with tsup into CJS and ESM bundles with type declarations, and the repo is a Turborepo/pnpm-workspace monorepo that also contains a Next.js website/ package for docs and demos.

Code Quality - There is no automated unit test suite; the test/ directory only contains benchmark HTML generators for manually profiling relayout performance, so correctness relies on manual/visual verification and community usage rather than CI-enforced tests. The code itself is compact and well-commented, with JSDoc on every public prop explaining defaults and behavior, plus a development-mode console warning that catches a common misuse (wrapping block elements instead of inline text).

API Design - The public API is deliberately minimal: a single <Balancer> component with sensible defaults (ratio=1, preferNative=true, as='span') that requires no configuration to use, plus an optional <Provider> for multi-instance pages. Props are documented inline via JSDoc and the README, and the component transparently degrades to native CSS balancing on supporting browsers, keeping the JS payload and behavior invisible to consumers in the common case.