Show Character Limit jQuery Plugin to report # of characters remaining in text input or text area.
JavaScript CSS
Switch branches/tags
Clone or download
Permalink
Failed to load latest commit information.
lib add events Jul 9, 2011
.gitignore
LICENSE add apache license Jul 1, 2012
README.markdown Change name of events, to be more specific, name-spaced. Jan 20, 2015
bower.json
jquery.show_char_limit.html
jquery.show_char_limit.js Change name of events, to be more specific, name-spaced. Jan 20, 2015
jquery.show_char_limit_spec.js Change name of events, to be more specific, name-spaced. Jan 20, 2015
package.json lowercase name Oct 25, 2014
showCharLimit.jquery.json upgrade to 1.5.0, adding bower and npm (?) Oct 25, 2014
spec_helper.js first commit-- adding ScrewUnit JS specs Nov 10, 2009

README.markdown

Summary

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

Features

Works on both 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 another DOM element 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 explicitly provide the element.

Usage

$([selector]).show_char_limit([max_length], [options]);
$([selector]).showCharLimit([max_length], [options]);
$([selector]).showCharLimit([options]);

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. The 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 that will appear at different widths.
  • 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('check.show-char-limit');
  • listen for 'ok.show-char-limit' when validation passes (every keystroke), eg. jQuery('input').show_char_limit(...).bind('ok.show-char-limit', function() {})
  • listen for 'error.show-char-limit' when validation fails with too many characters (every keystroke), eg. jQuery('input').show_char_limit(...).bind('error.show-char-limit', function() {})

Legacy events are supported with the deprecated_events flag set. It is set in version 1.6, but will be turned off in future versions:

  • showLimit (deprecated) => check.show-char-limit
  • validationOk (deprecated) => ok.show-char-limit
  • validationError (deprecated) => error.show-char-limit

Demo

Demo

Tests

Open jquery.show_char_limit.html in a browser.

History

  • 1.6.0: rename events
  • 1.5.x: bower support
  • 1.4.0: introduced strip and newline_cost attribute
  • 1.3.1: introduced status_min attribute

Legal

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