Library / SDK
shuding/react-wrap-balancer avatar
shuding/react-wrap-balancer

Four props, one browser table, and a version that has not moved

Simple React Component That Makes Titles More Readable

4,214 stars60 forksHTMLMIT

At a glance

What is it?
The component itself is tiny, so the interesting part of this package is what surrounds it: four optional props with defaults that lean on native CSS balancing, a compatibility table written entirely around ResizeObserver, a package.json that ships nothing but dist, and a version string sitting at 1.1.1.
Who is it for?
Judge this package on two dates and one file. The published version is 1.1.1 from 2024-05-25, the branch itself was last pushed on 2026-03-25, and package.json is what tells you which of the two you have.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly HTML, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shuding/react-wrap-balancer4,214 ★ · +4
Star history
Repository2026-09-232026-11-14
shuding/react-wrap-balancer4.2k4.2k

4 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

npm i react-wrap-balancer, then four props decide the rest

Installation is one command:

bash
npm i react-wrap-balancer

Everything else about the library is the Balancer component and its four optional props. `as` chooses the tag wrapped around the text and defaults to `span`, so the component adds no display of its own and inherits whatever the surrounding heading gives it. `ratio` takes a value from 0 to 1 and defaults to `1`, and it is the only knob that changes how even the line lengths end up. `preferNative` defaults to `true`, which means the rebalancing logic is skipped whenever the browser supports native CSS text balancing. `nonce` has no default and exists for one purpose, described in the next section.

The component wraps whatever text you put inside it:

jsx
import Balancer from 'react-wrap-balancer'

// ...

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

The stated purpose is narrower than the name suggests: it improves wrapping so that a title does not end with a single word on its own line.

The compatibility table is written entirely around ResizeObserver

The README gives two tables, one per platform group, and attributes the differences between browsers to one API: ResizeObserver. The desktop floor is Chrome 64, Edge 79, Safari 13.1, Firefox 69 and Opera 51, with Internet Explorer marked as no support. The mobile floor is Chrome 64, Safari 13.4, Firefox 69, Opera 47 and WebView Android 64. Safari and Opera are the two entries where desktop and mobile disagree.

The advice for anything older is a polyfill for that API or a browser upgrade. What the tables do not cover is the default path the component actually takes. `preferNative` defaults to `true`, so the first thing a modern browser is asked for is native CSS balancing, and the README says nothing about which browser versions have that. The proposal behind the native behaviour is linked from the credits as text-wrap: balance, still in a CSS draft.

The component injects an inline script, and the nonce prop exists for that

The `nonce` prop is documented as the attribute that allows inline script injection by the component. That single line explains why the component needs it: it writes a script tag into the page, and a site serving a strict Content Security Policy will block it unless the nonce matches. With the prop omitted there is no nonce to send, so the behaviour of the component under a policy that does not allow inline scripts is left entirely to the reader to work out.

This is also the part that makes the `preferNative` default interesting. With `preferNative` at its default of `true`, the component uses native CSS text balancing where supported instead of the re-balance logic. What the documentation does not offer is a table saying which browsers land in that group, so the deciding factor for a locked-down deployment is something the reader has to determine outside this repository.

Provider exists to share the script and shrink the HTML

Wrapping an entire app in Provider is described as recommended but optional, and the reason given is twofold: the Balancer components then share the re-balance logic, and the HTML gets smaller. The mechanism is not explained further, but the effect is stated plainly, which is enough to know when to reach for it: many Balancers on one page, and markup that has grown large enough that you care.

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

// ...

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

One detail is worth pinning down: it is a named export next to the default Balancer export, so the import style differs between the two.

package.json ships only dist, with the entry points typed by hand

The published surface is one directory. `files` contains `dist` and nothing else, and the three entry fields point into it by hand, so a CommonJS consumer, a bundler and a TypeScript project each read a different file:

json
"main": "dist/index.js",
"module": "dist/index.mjs",
"types": "dist/index.d.ts",
"files": ["dist"],

The build is a single tsup invocation over one entry file, and the two dev scripts differ only by the watch flag:

json
"scripts": {
  "build": "tsup src/index.tsx",
  "dev": "tsup src/index.tsx --watch",
  "dev:website": "turbo run dev --filter=website..."
}

Because only dist is published, the source, the test directory and the website never reach an installed copy. Anyone auditing what they are about to bundle has to read the repository rather than the installed package, and the type declarations are read from dist/index.d.ts rather than from checked-in source.

The peer range starts at 16.8.0 and then stops caring

React is the only peer dependency, and its range reads like three separate intentions collapsed into one line:

json
"peerDependencies": {
  "react": ">=16.8.0 || ^17.0.0 || ^18"
}

The first clause is open ended. Anything at or above 16.8.0 satisfies it, including every major version released since, which means the two clauses after it add nothing to what will install. The floor is what the range really communicates: 16.8.0, the release that added hooks. Nothing in the package.json caps the top end, so a consumer on a much newer React gets a clean install rather than a warning.

The development dependencies tell a narrower story. React is pinned at ^18.2.0 with @types/react at ^18.0.26, TypeScript at ^4.8.4, tsup at ^6.4.0 and turbo at ^1.6.3, so what gets compiled here has only ever been built against that generation. A peer range that accepts everything, backed by one that builds against a single major, is the kind of gap worth knowing about before the first breaking release in React itself.

Version 1.1.1, released in May 2024, is what the branch still carries

package.json says 1.1.1, and 1.1.1 is the newest release on record, dated 2024-05-25. Before that came 1.1.0 on 2023-08-15 and 1.0.0 on 2023-06-15. The branch itself was pushed on 2026-03-25, so the tree has moved well past the tag without a version bump to show for it. Nothing in the tree carries a deprecation notice, an end-of-life statement or a support policy, and the README does not comment on release cadence.

The repository is larger than the package it produces. Alongside src and test there is a website directory, a turbo.json, a tsup.config.ts, a tsconfig.json, a pnpm-workspace.yaml and a pnpm-lock.yaml, and the third script drives the website through turbo with a filter. What the scripts do not include is anything that runs the test directory, so the checks are wired up somewhere other than package.json, or not at all in the published manifest. The README credits Shu Ding, who created the project in 2022, and thanks Emil Kowalski for testing and feedback.

Editorial conclusion

Judge this package on two dates and one file. The published version is 1.1.1 from 2024-05-25, the branch itself was last pushed on 2026-03-25, and package.json is what tells you which of the two you have. Before adding it, check whether your React version satisfies the peer range as written, because its first clause accepts anything at or above 16.8.0, and decide whether you can ship a nonce for the inline script it injects. If your target browsers are older than the table, the README's answer is a ResizeObserver polyfill, not a fallback path. And if you want the rebalancing logic instead of the browser's own, remember that the default points the other way.

Frequently asked questions

What is a React component wrapper, and is react-wrap-balancer one?

This package exports a single component, Balancer, which wraps text content inside a heading so that it does not leave a single word alone on the last line, plus a Provider for sharing the re-balance logic across many instances.

Which browsers does react-wrap-balancer support?

Desktop floor: Chrome 64, Edge 79, Safari 13.1, Firefox 69, Opera 51, with Internet Explorer marked no support. Mobile floor: Chrome 64, Safari 13.4, Firefox 69, Opera 47, WebView Android 64. The README attributes the differences to the ResizeObserver API.

What does the ratio prop change in react-wrap-balancer?

It sets how balanced the result should be, accepts a value from 0 to 1 and defaults to 1. It is the only prop that changes the behaviour of the wrapping itself rather than the tag, the script or the policy handling.

How does react-wrap-balancer behave under a strict Content Security Policy?

The component injects an inline script, and the optional nonce prop is documented as the attribute for allowing that injection. No default nonce is given, so a site that does not allow inline scripts has to supply one.

Is react-wrap-balancer still being released?

The newest release on record is 1.1.1 from 2024-05-25 and package.json still carries that version. The main branch was pushed on 2026-03-25, the repository is not archived, and no maintenance policy is stated anywhere in the tree.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. shuding/react-wrap-balancer on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shuding-react-wrap-balancer.svg)](https://hysenlabs.com/projects/shuding-react-wrap-balancer)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shuding-react-wrap-balancer.svg)](https://hysenlabs.com/projects/shuding-react-wrap-balancer)

Was this useful?