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.
npm i balanced-text
After installation, you can import the JS file into your project using this snippet:
import { balanceText } from 'balanced-text'
Then run:
balanceText()
<element class='has-text-balanced'>Lorem…</element>
/* 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
.
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 are passed as an optional object.
balanceText({
elements: '.has-text-balanced',
watch: false,
debounce: 200,
lazyBalance: false,
disableWait: false
})
Change which elements are balanced.
- Type:
String
- Default:
'.has-text-balanced'
balanceText({ elements: '.balance-text' })
Any string that works with document.querySelectorAll()
is valid.
If the window is resized, rebalance the text.
- Type:
Boolean
- Default:
false
balanceText({ watch: true })
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.
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 })
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 })
- 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.
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
' '
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.
https://github.com/Nick-Mazuk/balanced-text/issues
©2020 Nick Mazuk. Code released under the MIT license.