Registry / web-framework / react-wrap-balancer

react-wrap-balancer

library1.1.1jsnpmunverified

React Wrap Balancer is a React component designed to improve the readability of text, particularly titles and headings, by intelligently balancing line wraps to prevent awkward single-word lines or uneven text blocks. Its current stable version is 1.1.1, with an active release cadence that frequently introduces bug fixes and minor enhancements. A key differentiator is its ability to automatically detect and prioritize the native CSS `text-wrap: balance` property for optimal performance, falling back to a JavaScript-based solution when native browser support is unavailable. For applications utilizing multiple `<Balancer>` instances, the optional `<Provider>` component is recommended to centralize and share the re-balancing logic, which reduces HTML size and improves overall efficiency, especially when the native CSS feature is not available. The library ships with TypeScript types, ensuring a robust developer experience.

web-framework serialization

npm install react-wrap-balancer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-WRAP-BALANCE

react-wrap-balancer

web-frameworkjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Balancer

✓ import Balancer from 'react-wrap-balancer'

✗ import { Balancer } from 'react-wrap-balancer'

The `Balancer` component is a default export.

Provider

✓ import { Provider } from 'react-wrap-balancer'

✗ import Provider from 'react-wrap-balancer'

The `Provider` component is a named export. It's recommended to wrap your app with it for shared logic and reduced HTML size when using multiple `Balancer` instances.

BalancerProps

✓ import type { BalancerProps } from 'react-wrap-balancer'

Importing type definitions for TypeScript usage.

This example demonstrates wrapping a React application with `<Provider>` for shared re-balance logic and using `<Balancer>` to balance the text content of titles and subtitles, improving readability.

import { Provider } from 'react-wrap-balancer'; import Balancer from 'react-wrap-balancer'; import React from 'react'; import ReactDOM from 'react-dom/client'; function App() { return ( <Provider> <div style={{ maxWidth: '400px', margin: '50px auto', fontFamily: 'sans-serif' }}> <h1> <Balancer> This is a very long title that needs to be perfectly balanced for optimal readability across various screen sizes. </Balancer> </h1> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. </p> <h2> <Balancer ratio={0.8}> Another balanced subtitle for improved typography. </Balancer> </h2> </div> </Provider> ); } const root = ReactDOM.createRoot(document.getElementById('root') ?? document.createElement('div')); root.render(<App />);

Debug

Known issues

breakingStarting with v1.0, `react-wrap-balancer` prioritizes the native CSS `text-wrap: balance` feature. If native support is detected, the `ratio` prop on `<Balancer>` components will be ignored.

fix

Be aware that the `ratio` prop may not apply in modern browsers. If you need a specific balance ratio regardless of native support, consider setting `preferNative={false}` on the `<Balancer>` component (though this is generally not recommended for performance).

affects: >=1.0.0

gotchaWhen using multiple `<Balancer>` components, it is strongly recommended to wrap your entire application or the relevant section with the `<Provider>` component. This allows for shared re-balance logic, reduces HTML size, and optimizes performance.

fix

Wrap your root component or the highest common ancestor of your `<Balancer>` components with `<Provider>`: `<Provider><App /></Provider>`.

affects: >=0.3.0

gotchaThe library relies on the `ResizeObserver` API for responsive balancing. Older browsers or environments without `ResizeObserver` support (e.g., IE) will not function correctly.

fix

Ensure target browsers meet the minimum version requirements (Chrome 64+, Edge 79+, Safari 13.1+, Firefox 69+). For unsupported browsers, consider adding a `ResizeObserver` polyfill if necessary.

affects: all

gotchaIf you are using Content Security Policy (CSP), the inline script tags generated by `react-wrap-balancer` will require a `nonce` attribute to be allowlisted. Otherwise, a CSP error will occur.

fix

Pass a `nonce` prop to your `<Balancer>` component: `<Balancer nonce="your-csp-nonce">`.

affects: all

gotchaPlacing `<Balancer>` within an element that has `display: flex` or `display: grid` can sometimes lead to unexpected layout issues or incorrect balancing, especially if the flex/grid container's sizing interferes with the text flow.

fix

Try to place `<Balancer>` inside block-level elements. If it must be within a flex or grid container, ensure the container's styles do not aggressively constrain the text element, or consider using a wrapper `span` or `div` inside the flex/grid item.

affects: all

Errors

Common errors & fixes

ReferenceError: ResizeObserver is not defined

The browser or environment running the code does not support the `ResizeObserver` API, which `react-wrap-balancer` uses for dynamic text re-balancing.

fix

Upgrade your browser to a version that supports `ResizeObserver` (e.g., Chrome 64+, Firefox 69+, Safari 13.1+) or include a `ResizeObserver` polyfill in your project.

Warning: Extra attributes from the server. This is a hydration error. Your app may not render correctly.

Inconsistencies between the server-rendered and client-rendered HTML, often related to dynamically injected scripts or attributes, which were present in early versions.

fix

Ensure you are using `react-wrap-balancer` version `0.2.4` or higher, which includes a fix for hydration warnings on script tags. If using CSP, provide a `nonce` prop.

Balancer not correctly setting text-wrap: balance

The native CSS `text-wrap: balance` might not be detected or applied, or the JavaScript fallback is not engaging as expected. This was a specific bug fixed in version 1.1.0.

fix

Upgrade to `react-wrap-balancer@1.1.0` or newer. Ensure `<Provider>` is wrapping your application. If you explicitly want to force the JavaScript fallback, set `preferNative={false}` on the `<Balancer>` component, though this is generally less performant.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for all React components.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/shuding/react-wrap-balancer ↗

packagehttps://www.npmjs.com/package/react-wrap-balancer ↗

homepagehttps://react-wrap-balancer.vercel.app ↗