Code : Web Hackery :

TextGauge jQuery Plugin

We've all been there. Fill in enough forms online, and you'll eventually hit the textarea that has a character limit. We've seen all the usual treatments: "The Keystroke Countdown," "The Arbitrary Letter Target," and the worst UX sin of all: "The Hard-Limit Hammer."

When I was faced with solving this particular problem recently, I decided that there had to be a better solution. There are two major problems to solve with a length limited input field:

  1. How to indicate what the limit actually is
  2. How to show the user how far into (or over) the limit they are

I believe that my textGauge plugin solves these problems.

First, the biggest problem with all of typical approaches is that nobody who isn't a professional editor (and probably only a few of those) has any innate sense of an association between their writing and a number of letters. We don't think in letters. We think in ideas. It can get even worse when the limit is imposed by a VARCHAR limit in a database configured such that you really have to count bytes, not characters. Do you know how many bytes long this paragraph is?

What we need is some abstraction layer between the character (or byte) limit and what we're typing—something visual, familiar, and dynamic. When we get near the limit, we need to know so we can wrap things up. When we go over the limit, we need to know that too, and not because we can't type anymore—when we go over the limit, we should be able to see how far over the limit we are, and we should be able to edit our writing down to fit the target.

Here is the jQuery plugin I wrote to solve this problem. Try it out:

This textarea is limited to 50 characters.
You have exceeded the limit.

The markup for the above demo is pretty straight-forward. We just have a textarea with appropriate styling, and a div containing our error message, with display: none.

<div>
    <div class="field-description">This textarea is limited to 50 characters.</div>
    <textarea rows="4" cols="80" id="textGaugeDemo1"></textarea>
    <div class="field-err">You have exceeded the limit.</div>
</div>


.demo .field-err {
    display: none;
    font-size: medium; 
    color: red; 
}
.demo textarea.err {
    background-color: #fee;
}

Next, we initialize the plugin on the element using standard jQuery plugin syntax. The code below also binds handlers to two available textGauge events, textGauge_wentOverLimit and textGauge_fellUnderLimit, to show and hide the error messaging.

$("#textGaugeDemo1")
    .textGauge({limit:50})
    .bind('textGauge_wentOverLimit', function(e){
        $(e.currentTarget).addClass('err').parent().find('.field-err').fadeIn('fast');
    })
    .bind('textGauge_fellUnderLimit', function(e){
        $(e.currentTarget).removeClass('err').parent().find('.field-err').fadeOut('fast');
    });

The following options are available on initialization:

Option Value Default Description
limit integer 100 the limit to measure the input text against
limitUnits 'bytes' or 'chars' 'chars' what to count against the limit
recalculateDelay 0 or positive integer 100 number of milliseconds to wait between recounts while typing, or 0 to recalculate on every keypress
warningThreshold float value between 0 and 1 0.8 percentage of limit at which to trigger the near-limit warning
animate boolean true animate the limit meter; recommended false for larger limited fields such as text areas, especially when recalculateDelay is set to 0

TextGauge implements the following custom events, which you can bind to control behaviors linked to the character or byte count of the text field. All triggered events receive the event object as an argument.

Event Description
textGauge_fellUnderWarningThreshold Triggered when field edits cause the count to fall below the warning threshold
textGauge_wentOverWarningThreshold Triggered when field edits cause the count to go above the warning threshold
textGauge_fellUnderLimit Triggered when field edits cause the count to fall below the limit
textGauge_textAtLimit Triggered when field edits cause the count to reach the limit
textGauge_wentOverLimit Triggered when field edits cause the count to go above the limit

The following methods are also implemented:


    /**
     * init - Initialize the textGauge.
     *        this is the same as calling .textGauge([options]);
     */
    $(#"textGaugeDemo1").textGauge('init' [, options ]);

    /**
     * destroy - Removes textGauge from the selected elements and undoes 
     *           any alterations that were made during init
    $("#textGaugeDemo1").textGauge('destroy');

    /**
     * recount - forces textGauge to update its count, 
     *           typically after you have altered the text  programmatically
     */
    $("#textGaugeDemo1").textGauge('recount'); 

So that's textGauge. Hope you like it. You can download the source-code for this plugin at github.com/knassar/textGauge. Enjoy!