Summary

jQuery plugin to display interactive character limit feedback about a text field or textarea.

Features

Works on text inputs or text areas.

The caller provides the "status" element to display the feedback. If no element can be found, a new one is created immediately after the text input.

The current status can be formatted as count down, count up, or some other format.

Optionally, for nicer visual styling, the plugin will add a class to any DOM other elements when the field is over the limit. This is convenient as it allows turning an element red, or displaying a hidden div with more detailed error message.

This plugin does nothing to enforce the character limit. This is intentional.

It uses a heuristic to find the status field: appends "_status" to the id of the text element. For example, if the text field ID is tweet, the status field is tweet_status. You can provide your own "suffix" instead of status, or if you want, just explicitly provide the element.

Usage

Options:

• maxlength. The maximum number of characters allowed in the input. May also be passed as the first parameter. This value can (and will be) overriden by an attribute named maxlength on the input element.
• status_element: element to receive the status message. It can be a jQuery object, element or DOM id. Overrides status_element_suffix
• status_element_suffix: a string appended to the src element's id to identify the status element. For this markup: <input type="text" id="name"/><span id="name_lim">20 chars</span>, pass _lim. Default value is __status. If the element is not found, a SPAN is created immediately after the input.
• error_element. An element (or set of elements) have CSS class error added when there are too many characters in the target element. Can be a jQuery object, element or DOM id.
• error_class. Alternate class set on error_element above. Defaults to error.
• status_style. Default is text, which displays a short phrase of "X characters left" or "X characters over". You may also pass chars_typed, which displays the number of characters the user has typed (see twitter). Or chars_left, which counts down to zero.
• status_min = 0. Lower limit when status is shown. Useful if you don't want to warn the user until she gets close to the limit. Defaults to 0.
• newline_cost = 1. Additional "penalty" to add core carriage returns or linefeeds. Useful to estimate text layouts.
• strip = true. Remove whitespace characters from the beginning and end of the text before counting characters. Does not remove them from the actual value.

Events

• to manually trigger updating of the counter, $(text element).trigger('showLimit');
• listen for 'validationOk' when validation passes (every keystroke), eg. jQuery('input').show_char_limit(...).bind('validationOk', function() {})
• listen for 'validationError' when validation fails with too many characters (every keystroke), eg. jQuery('input').show_char_limit(...).bind('validationError', function() {})

Demo

Demo

Tests

Open jquery.show_char_limit.html in a browser.

History

• 1.4.0: introduced strip and newline_cost attribute
• 1.3.1: introduced status_min attribute

Legal

Copyright (c) 2005-2012 Andrew J. Peterson Apache License