wrap-balancer

vanilla-wrap-balancer

A dependency-free, framework-free port of react-wrap-balancer. Drop one <script> tag onto any plain HTML page and your titles stop dropping a single lonely word onto the last line.

🇰🇷 한국어 문서: README.ko.md

_{Same sentence, same width: 기본 줄바꿈 (default) strands a single word on the last line, while vanilla-wrap-balancer evens the lines out. (Korean, word-break: keep-all.)}

The core binary-search algorithm (relayout) is ported verbatim from react-wrap-balancer (MIT © Shu Ding). This package only re-implements the parts React used to provide — unique id generation, inline styling, native feature detection, "re-balance on content change", and observer cleanup — so it can run with no build step and no framework.

• ✅ ~3.8 KB minified, zero dependencies
• ✅ Works with a plain <script> tag → exposes a global WrapBalancer (UMD)
• ✅ Auto-initialises [data-br-balance] elements; also a small programmatic API
• ✅ Uses native CSS text-wrap: balance when available, JS binary-search otherwise
• ✅ Re-balances on container resize (ResizeObserver) and content change (MutationObserver)
• ✅ Proven byte-identical to the React original across 644 randomized cases — see Equivalence & testing

---

The problem

When a heading wraps, the browser greedily fills each line, which often leaves a single word stranded on the last line:

Make your titles more
readable on every screen
size                          ← lonely orphan

Balancing redistributes the words so every line is roughly equal width:

Make your titles
more readable on
every screen size             ← balanced

---

Install

Option A — <script> tag (recommended for plain HTML pages)

Load it straight from the jsDelivr CDN — nothing to install or build:

<script src="https://cdn.jsdelivr.net/gh/Mineru98/vanilla-wrap-balancer@main/wrap-balancer.min.js"></script>

@main always serves the latest commit (jsDelivr mirrors GitHub). Prefer to self-host? Download wrap-balancer.min.js and reference it locally instead:

<script src="wrap-balancer.min.js"></script>

Option B — ES module / bundler

The UMD file also exposes module.exports, so bundlers can import it:

import WrapBalancer from './wrap-balancer.js'
WrapBalancer.balance('.title')

For native <script type="module">, the file attaches the global as a side effect:

<script type="module">
  import './wrap-balancer.js'
  WrapBalancer.balance('.title')
</script>

---

Quick start (no JavaScript to write)

Add data-br-balance to any text element. The script balances it on load, after web fonts settle, and on every resize:

<h1 data-br-balance>The quick brown fox jumps over the lazy dog tonight</h1>

<script src="https://cdn.jsdelivr.net/gh/Mineru98/vanilla-wrap-balancer@main/wrap-balancer.min.js"></script>

That's the whole integration. See examples/01-quickstart.html.

Tip — where to put the marker. Put data-br-balance on the element that contains the text (e.g. the <h1>). The library wraps that element's children in an inline-block <span> and balances the span inside it — structurally identical to <h1><Balancer>…</Balancer></h1> in React.

---

Usage patterns

Pattern	File
Zero-JS auto-init	examples/01-quickstart.html
Programmatic API	examples/02-programmatic.html
Balance ratio slider	examples/03-ratio.html
Dynamic content	examples/04-dynamic.html
Before / after comparison	examples/05-comparison.html

Programmatic

Disable auto-init via data-auto="false" and drive it yourself:

<script src="https://cdn.jsdelivr.net/gh/Mineru98/vanilla-wrap-balancer@main/wrap-balancer.min.js" data-auto="false"></script>
<script>
  const handles = WrapBalancer.balance('.title', { ratio: 1, preferNative: true })
  // handles[0].rebalance()
  // handles[0].destroy()
</script>

Per-element options via data attributes

<h1 data-br-balance data-br-ratio="0.75" data-br-prefer-native="false">…</h1>

---

API

The global WrapBalancer object:

WrapBalancer.balance(target, options?) → handle[]

Balance one or many elements. target is a CSS selector string, an Element, a NodeList, or an array of elements. Idempotent — calling it again on the same element just updates options and re-balances (no double-wrapping). Returns an array of handles.