React Wrap Balancer

Common errors

• ReferenceError: ResizeObserver is not defined

  cause 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.

  cause 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

  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.
  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.

Warnings

• breaking 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.
  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).
• gotcha 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.
  Fix: Wrap your root component or the highest common ancestor of your `<Balancer>` components with `<Provider>`: `<Provider><App /></Provider>`.
• gotcha The 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.
• gotcha 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.
  Fix: Pass a `nonce` prop to your `<Balancer>` component: `<Balancer nonce="your-csp-nonce">`.
• gotcha 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.
  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.

Install

• npm install react-wrap-balancer npm
• yarn add react-wrap-balancer yarn
• pnpm add react-wrap-balancer pnpm

Imports

• Balancer
  wrong:

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

  correct:

  import Balancer from 'react-wrap-balancer'

  The `Balancer` component is a default export.
• Provider
  wrong:

  import Provider from 'react-wrap-balancer'

  correct:

  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.

Quickstart

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 />);