{"id":11911,"library":"react-wrap-balancer","title":"React Wrap Balancer","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/shuding/react-wrap-balancer","tags":["javascript","react","wrapping","text","typography","typescript"],"install":[{"cmd":"npm install react-wrap-balancer","lang":"bash","label":"npm"},{"cmd":"yarn add react-wrap-balancer","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-wrap-balancer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React components.","package":"react","optional":false}],"imports":[{"note":"The `Balancer` component is a default export.","wrong":"import { Balancer } from 'react-wrap-balancer'","symbol":"Balancer","correct":"import Balancer from 'react-wrap-balancer'"},{"note":"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.","wrong":"import Provider from 'react-wrap-balancer'","symbol":"Provider","correct":"import { Provider } from 'react-wrap-balancer'"},{"note":"Importing type definitions for TypeScript usage.","symbol":"BalancerProps","correct":"import type { BalancerProps } from 'react-wrap-balancer'"}],"quickstart":{"code":"import { Provider } from 'react-wrap-balancer';\nimport Balancer from 'react-wrap-balancer';\nimport React from 'react';\nimport ReactDOM from 'react-dom/client';\n\nfunction App() {\n  return (\n    <Provider>\n      <div style={{ maxWidth: '400px', margin: '50px auto', fontFamily: 'sans-serif' }}>\n        <h1>\n          <Balancer>\n            This is a very long title that needs to be perfectly balanced for optimal readability across various screen sizes.\n          </Balancer>\n        </h1>\n        <p>\n          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.\n        </p>\n        <h2>\n          <Balancer ratio={0.8}>\n            Another balanced subtitle for improved typography.\n          </Balancer>\n        </h2>\n      </div>\n    </Provider>\n  );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root') ?? document.createElement('div'));\nroot.render(<App />);","lang":"typescript","description":"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."},"warnings":[{"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).","message":"Starting 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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Wrap your root component or the highest common ancestor of your `<Balancer>` components with `<Provider>`: `<Provider><App /></Provider>`.","message":"When 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.","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"The library relies on the `ResizeObserver` API for responsive balancing. Older browsers or environments without `ResizeObserver` support (e.g., IE) will not function correctly.","severity":"gotcha","affected_versions":"all"},{"fix":"Pass a `nonce` prop to your `<Balancer>` component: `<Balancer nonce=\"your-csp-nonce\">`.","message":"If 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Placing `<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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The browser or environment running the code does not support the `ResizeObserver` API, which `react-wrap-balancer` uses for dynamic text re-balancing.","error":"ReferenceError: ResizeObserver is not defined"},{"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.","cause":"Inconsistencies between the server-rendered and client-rendered HTML, often related to dynamically injected scripts or attributes, which were present in early versions.","error":"Warning: Extra attributes from the server. This is a hydration error. Your app may not render correctly."},{"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.","cause":"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.","error":"Balancer not correctly setting text-wrap: balance"}],"ecosystem":"npm"}