JarCastingjQuery Text Counter Plugin
A jQuery plugin for counting and limiting characters/words on text input, or textarea, elements.
Installation
Include script after the jQuery library:
<script src="/path/to/textcounter.min.js"></script>
or
npm
Install using npm:
npm install jquery-text-counter
or
Bower
Install using bower:
bower install jquery-text-counter
Usage
Basic usage (view editable code):
$('input').textcounter();
Define maximum words and allow further input (view editable code):
$('input').textcounter({
type: "word",
max: 15,
stopInputAtMaximum: false
});
Define minimum characters and set custom countDownText (view editable code):
$('input').textcounter({
min: 20,
countDownText: "%d characters remaining"
});
Example
Elements
By default the plugin creates and appends the following element after the input:
<div class="text-count-wrapper">
Total Count:
<span class="text-count">0</span>
</div>
If an error is present it is appended within the element. The input gains the inputErrorClass and count wrapper gains the counterErrorClass as defined in the options:
<input name="sample" class="error" />
<div class="text-count-wrapper error">
Total Count:
<span class="text-count">0</span>
<div class="error-text">Error message text</div>
</div>
Callbacks
maxcount(el){}
Fires when a counter reaches the maximum word/character count.
mincount(el){}
Fires when a counter reaches the minimum word/character count.
init(el){}
Fires after the counter is initialized.
maxunder(el){}
Fires when counter is under max limit.
minunder(el){}
Fires when counter is under min limit.
Options
type : "character", // "character" or "word"
min : 0, // minimum number of characters/words
max : 200, // maximum number of characters/words, -1 for unlimited, 'auto' to use maxlength attribute, , 'autocustom' to use a custom attribute for the length (must set "autoCustomAttr")
autoCustomAttr : "counterlimit", // custom attribute name with the counter limit if the max is 'autocustom'
countContainerElement : "div", // HTML element to wrap the text count in
countContainerClass : "text-count-wrapper", // class applied to the countContainerElement
textCountMessageClass : "text-count-message", // class applied to the counter message
textCountClass : "text-count", // class applied to the counter length (the count number)
inputErrorClass : "error", // error class appended to the input element if error occurs
counterErrorClass : "error", // error class appended to the countContainerElement if error occurs
counterText : "Total Count: %d", // counter text
errorTextElement : "div", // error text element
minimumErrorText : "Minimum not met", // error message for minimum not met,
maximumErrorText : "Maximum exceeded", // error message for maximum range exceeded,
displayErrorText : true, // display error text messages for minimum/maximum values
stopInputAtMaximum : true, // stop further text input if maximum reached
countSpaces : false, // count spaces as character (only for "character" type)
countDown : false, // if the counter should deduct from maximum characters/words rather than counting up
countDownText : "Remaining: %d", // count down text
countExtendedCharacters : false, // count extended UTF-8 characters as 2 bytes (such as Chinese characters)
twoCharCarriageReturn : false, // count carriage returns/newlines as 2 characters
countOverflow : false, // display text overflow element
countOverflowText : "Maximum %type exceeded by %d", // count overflow text
countOverflowContainerClass : "text-count-overflow-wrapper", // class applied to the count overflow wrapper
minDisplayCutoff : -1, // maximum number of characters/words above the minimum to display a count
maxDisplayCutoff : -1, // maximum number of characters/words below the maximum to display a count
// Callback API
maxunder : function(el){}, // Callback: function(element) - Fires when counter is under max limit
minunder : function(el){}, // Callback: function(element) - Fires when counter is under min limit
maxcount : function(el){}, // Callback: function(element) - Fires when the counter hits the maximum word/character count
mincount : function(el){}, // Callback: function(element) - Fires when the counter hits the minimum word/character count
init : function(el){} // Callback: function(element) - Fires after the counter is initially setup
Development
- Source hosted at GitHub
- Report issues, questions, feature requests on GitHub Issues
Authors
Contributors
- stgeneral - count length newlines fix
- moinism - callback API
- benr77 - bower support
- SammyB - countdown starting count fix
- eprincen2 - jQuery Validate compatibility fix
- Hexodus - minunder/maxunder events
- juliovedovatto / alvaro-canepa - multiple classes support for counter container
- dtipson - multiple classes error fix
- jmichalicek - count carriage returns/newlines as 2 characters
- diptopol -
stopInputAtMaximumwithtwoCharCarriageReturncount fix, trimmed newline calculation fix, maximum text reached condition fix, text count overflow notification - trevorloflin -
minDisplayCutoffandmaxDisplayCutoffoptions - t3mujin - autocustom support (maxlength workaround), text fixes
- goranmiric - accessibility enhancements