Balanced-text NPM

Balanced Text

balanced text demo

A performance-optimized script for balancing text in browser. text-wrap: balance is in the CSS Text Module Level 4 draft. This JS script is a polyfill and is dependency-free.

Initial benchmarks are faster than both Adobe's and NY Time's polyfills.

Demo

Quick Install

npm i balanced-text

Import

After installation, you can import the JS file into your project using this snippet:

import { balanceText } from 'balanced-text'

Then run:

balanceText()

HTML

<element class='has-text-balanced'>Lorem…</element>

CSS (optional)

/* For when the CSS spec is available */
.has-text-balanced {
    text-wrap: balance;
}

The JS will only run if your browser does not support text-wrap: balance.

CDN (Alternative)

https://www.jsdelivr.com/package/npm/balanced-text

<script src='https://cdn.jsdelivr.net/npm/balanced-text@latest/balance-text.min.js'>
    balanceText()
</script>

Options

Options are passed as an optional object.

balanceText({
    elements: '.has-text-balanced',
    watch: false,
    debounce: 200,
    lazyBalance: false,
    disableWait: false
})

Elements

Change which elements are balanced.

Type: String
Default: '.has-text-balanced'

balanceText({ elements: '.balance-text' })

Any string that works with document.querySelectorAll() is valid.

Watch

If the window is resized, rebalance the text.

Type: Boolean
Default: false

balanceText({ watch: true })

Debounce

When watch: true, balanceText is debounced by default. That reduces jank whenever the window is resized. Use debounce to change the timing.

Type: Integer (milliseconds)
Default: 200

balanceText({ debounce: 200 })

Set debounce to 0 to eliminate it.

Lazy Balance

If you have many elements on your page that need balanced text, consider enabling lazy balancing.

When set to true, balanceText will only affect visible elements. Using IntersectionObserver, text will be automatically balanced when it enters the viewport. Because balanceText is fast, it should not introduce scroll jank.

Type: Boolean
Default: false

balanceText({ lazyBalance: true })

Disable Wait

By default, balanceText waits until the main thread is idle (see Timing). Enabling this option will make balanceText run as soon as possible. It may become render blocking. However, it can prevent the "flash" of unbalanced text.

Type: Boolean
Default: False

balanceText({ disableWait: true })

How it works

Wraps every word in a span
Gets the width of every word and space
Calculates the average line length
Places a br tag where the line breaks should go

This limits many performance drawbacks of other algorithms.

Limitations

This script does assume a few things about the HTML contents:

The HTML elements only contain text (no sub elements, including b, strong, a tags). Will be fixed in future versions.
The only line-break opportunities are spaces ' '