balanced-text

Balanced Text

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

Timing

The script uses requestIdleCallback if available (~75% support). This reduces the likelihood that it interrupts important functions.

If not, it uses requestAnimationFrame to minimize the chances of dropping a frame.

requestAnimationFrame is always used during lazyBalancing to minimize scroll jank.

Report Bug / Feature Request

https://github.com/Nick-Mazuk/balanced-text/issues

Copyright and license

©2020 Nick Mazuk. Code released under the MIT license.