View on GitHub

BalanceText

A jQuery plugin for balancing wrapping text in a web page

Download this project as a .zip file Download this project as a tar.gz file

BalanceText

A jQuery plugin to provide an alternate text wrapping algorithm. I hope to get this into the CSS spec, so it's implemented as a polyfill. It already appears in the CSS Text Module Level 4 Editor's Draft.

The default text rendering algorithm is:

  1. Add 1 word at a time to the current line until the next word won't fit.
  2. Break text so that the next word starts on a new line.
  3. Repeat until all text has been rendered.

That algorithm guarantees that the text is rendered using the least number of lines, but when text is centered and wraps to more than 1 line, it can produce visually undesirable results such as a long line of centered text followed by a short line of centered text. What I want is for the text to be balanced across lines. By "balanced across lines", I mean that the text is rendered so that the amount of text on each line is about the same. This plugin implements a line-breaking algorithm to do that automatically.

How it works

Here is a simple Balance Text setup:

    <style type="text/css">
    /* Plugin looks for elements with class named "balance-text" */
    .balance-text {
        text-wrap: balanced;   /* Apply (proposed) CSS style */
    }
    </style>

    <script src="jquery-1.9.1.min.js"></script>
    <script src="jquery.balancetext.min.js"></script>

See the demo provided for a working sample.

Balance Text will automatically run on any elements with balance-text class:

You may also manually trigger it, e.g. if you're dynamically adding text to the DOM:

    $('.my-class').balanceText();

You can use any selector of your choice (you may wish to use an ID or restrict the scope for performance). These will not re-balance on resize.

If you need to manually re-balance all triggered elements, use:

    $.fn.balanceTextUpdate();

To Balance Text and have it automatically update on resize, use:

    $.balanceText('.my-class');

Use from a CDN

Requirements

BalanceText is designed to run in most common browsers and implemented as a jQuery plugin. This means that the standard jQuery library is required for it to work. This plugin was last updated using jQuery 1.9.1, but it should work with all newer (and some older) versions of jQuery.

jQuery was used so that the code would be easier to write to work in most common browsers. None of the novel ideas introduced by this code require jQuery.

Code is minified using: UglifyJS

Changelog