DOCSEARCHbyAlgolia
Submit Docs

react-wrap-balancer

repository·main·Indexed 26 days ago

https://github.com/shuding/react-wrap-balancer

A React component that makes titles and text content more readable by automatically balancing line wraps to prevent awkward single-word lines across different viewport sizes. It provides a <Balancer> component for text wrapping and an optional <Provider> to optimize multiple balancers. The library utilizes a binary search algorithm or native CSS text-balancing and requires the ResizeObserver API.

Tokens
1.4K
Snippets
4
Records
8
Agent score
38%

What's inside react-wrap-balancer

  2. Use the <Balancer> component

    main

    Wrap your text content (like titles) with the <Balancer> component to automatically balance line wraps and avoid single words on the last line.

    import Balancer from 'react-wrap-balancer'

// ...

function Title() {
  return (
    <h1>
      <Balancer>My Awesome Title</Balancer>
    </h1>
  )
}

  3. Configure the <Balancer> component props

    main

    The <Balancer> component accepts the following props:

    • as (optional): The HTML tag to be used to wrap the text content. Defaults to span.
    • ratio (optional): The ratio of “balance-ness”, where 0 <= ratio <= 1. Defaults to 1.
    • preferNative (optional): If true, the component will skip re-balance logic and use native CSS text-balancing if supported by the browser. Defaults to true.
    • nonce (optional): The nonce attribute to allowlist inline script injection by the component.

  4. Optimize multiple balancers with <Provider>

    main

    If your application uses multiple <Balancer> components, wrap your application (or a common ancestor) with <Provider>. This allows them to share re-balance logic and reduces the overall HTML size.

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

// ...

function App() {
  return (
    <Provider>
      <MyApp/>
    </Provider>
  )
}

  5. Check browser support and ResizeObserver requirements

    main

    The library relies on the ResizeObserver API. If you need to support older browsers, you must provide a polyfill for ResizeObserver or upgrade the browser.

    Supported Desktop Browsers:

    • Chrome 64+
    • Edge 79+
    • Safari 13.1+
    • Firefox 69+
    • Opera 51+
    • IE is not supported.

    Supported Mobile Browsers:

    • Chrome 64+
    • Safari 13.4+
    • Firefox 69+
    • Opera 47+
    • WebView Android 64+

  6. Reference: BalancerOwnProps

    main

    The BalancerOwnProps interface defines the configuration options available to the Balancer component.

    interface BalancerOwnProps<ElementType extends React.ElementType = React.ElementType> extends React.HTMLAttributes<HTMLElement> {
  /**
   * The HTML tag to use for the wrapper element.
   * @default 'span'
   */
  as?: ElementType;
  /**
   * The balance ratio of the wrapper width (0 <= ratio <= 1).
   * 0 means the wrapper width is the same as the container width (no balance, browser default).
   * 1 means the wrapper width is the minimum (full balance, most compact).
   * @default 1
   */
  ratio?: number;
  /**
   * An option to skip the re-balance logic
   * and use the native CSS text-balancing if supported.
   * @default true
   */
  preferNative?: boolean;
  /**
   * The nonce attribute to allowlist inline script injection by the component.
   */
  nonce?: string;
}

  7. Use the Balancer component to balance text

    main

    The Balancer component makes titles and text more readable by automatically calculating an optimal width for the text wrapper to achieve a balanced layout. It uses a binary search algorithm to find the minimum width that prevents text overflow, or falls back to native CSS text-wrap: balance if supported by the browser.

    Key Props:

    • as: The HTML tag to use for the wrapper element. Defaults to 'span'.
    • ratio: The balance ratio of the wrapper width (0 to 1). 0 means the wrapper width is the same as the container width (no balance). 1 means the wrapper width is the minimum (full balance, most compact). Defaults to 1.
    • preferNative: An option to skip the re-balance logic and use native CSS text-balancing if supported. Defaults to true.
    • nonce: The nonce attribute to allowlist inline script injection by the component.

    Important Usage Note: In development, you will receive a warning if you wrap block-level elements (like <p> or <h1>) inside <Balancer>. Instead, you should place the <Balancer> component inside the block-level element to wrap text nodes directly.

    Correct: <h1><Balancer>My Title</Balancer></h1>
    Incorrect: <Balancer><h1>My Title</h1></Balancer>

  8. Configure the Balancer Provider

    main

    The Provider component is an optional wrapper that injects a global relayout function into the window object. This allows all child Balancer components to share the same logic and improves performance by avoiding redundant script injections.

    Props:

    • preferNative: An option to skip the re-balance logic and use native CSS text-balancing if supported. Defaults to true.
    • nonce: The nonce attribute to allowlist inline script injection by the component.
    • children: React nodes to be wrapped.