A performance-optimized script for balancing text in browser.
MIT License
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.
String
'.has-text-balanced'
balanceText({ elements: '.balance-text' })
Any string that works with document.querySelectorAll()
is valid.
If the window is resized, rebalance the text.
Boolean
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.
Integer
(milliseconds)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.
Boolean
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.
Boolean
False
balanceText({ disableWait: true })
br
tag where the line breaks should goThis limits many performance drawbacks of other algorithms.
This script does assume a few things about the HTML contents:
b
, strong
, a
tags). Will be fixed in future versions.' '
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.