Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/markembling/jquery-charactercounter-plugin

jQuery plugin for counting and displaying the available number of characters for a textarea.
https://github.com/markembling/jquery-charactercounter-plugin

character-count counter jquery jquery-plugin

Last synced: 3 months ago
JSON representation

jQuery plugin for counting and displaying the available number of characters for a textarea.

Awesome Lists containing this project

README 

        
# jQuery Character Counter Plugin



This jQuery plugin provides the ability to associate a character counter with a text area and includes the ability to customise the style and wording of the counter, along with rules for validity.



## Install



### Package Managers



You can install the plugin using NPM or Bower.



    npm install jquery-charactercounter-plugin

    bower install jquery-charactercounter-plugin



### Manually



If you'd prefer to install manually, download and include the `jquery.charactercounter.js` file in your project.



    



Ensure jQuery is also available and included before the plugin JS file.



## Usage



After including the plugin, use it by initialising it on the textarea(s) you wish to add character counting for.



    



    $('#example1').characterCounter();



The plugin can also be initialised on any number of textareas in one go.



    

    

    



    $('.counted').characterCounter();



By default, the plugin will create a new `div` element itself immediately following the textarea which will show the character count for that input.



### Providing a minimum and maximum character count



The plugin supports the idea of having a minimum and/or maximum character count which the user ought to provide. These can be provided using the `minChars` and `maxChars` options.



    

    



    

    

    

    

    



By default, the minimum is zero and the maximum is infinite, so it will never fall outside the valid state.



### Adding text to the counter



You can add text to the counter, both before the number and after.



    $('#example-text').characterCounter({

        maxChars: 200,

        postCountMessage: "characters left",

        postCountMessageSingular: "character left",

        zeroRemainingMessage: "No characters left",

        overrunPreCountMessage: "Please remove",

        overrunPostCountMessage: "characters",

        overrunPostCountMessageSingular: "character",

        positiveOverruns: true

    });



This example will give the following behaviour:



 - "200 characters left" when empty

 - "150 characters left" when filled below the maximum

 - "No characters left" when exactly 200 characters have been entered

 - "Please remove 15 characters" when filled with 215 characters

 - In both the valid and invalid states, singular options have been given to prevent messages like "1 characters left"



See the options section below for full details on what options are available, specifying options via object and data attributes, and default option values.



### Customize the character counter element



#### Styling



The plugin applies some classes which you're able to target in your CSS to make the counter look how you wish. By default, the classes applied by the plugin will be as shown in this table but you can customise these to any class names you wish (see options section below).



| State | Class

| ----- | -----

| Character count element (always applied) | `me-character-counter`

| Valid modifier - i.e. count is within any set minimum and maximums | `me-character-counter_valid`

| Invalid modifier - i.e. count is outside any set minimum and maximums | `me-character-counter_invalid`



The plugin will not add any styling of its own, and simply swaps out the classes depending on its state. Style however you like.



#### Use a different element



You can use any element on your page as the character counter instead of having the plugin create one for you. Simply create the character counter and provide a selector to the plugin using the `counterElement` option (see below for full details of options and specifying options).



    

    

    



The element can be anything, the plugin will simply use jQuery's `text()` method to swap out the contents with the appropriate count and message. It will also add/switch out the element's classes according to the validity of the length of the entered text however you can apply any of your own classes to your counter element in addition if you wish - the plugin will not interfere with those.



## Options



These options can be specified to customise the behaviour of the character counter. The default values are also given below.



| Option | Description | Default

| ------ | ----------- | -------

| `elementClass` | Class assigned to the character count element. | `"me-character-counter"`

| `validClass` | Class applied to the character counter (in addition to the `elementClass` value) when it is in a valid state. | `"me-character-counter_valid"`

| `invalidClass` | Class applied to the character counter (in addition to the `elementClass` value) when it is in an invalid state. | `"me-character-counter_invalid"`

| `maxChars` | Maximum allowed characters before being considered invalid. | `Infinity`

| `minChars` | Minimum number of characters allowed before being considered invalid. | `0` 

| `counterElement` | Element to use for the character counter. If `null`, one is created. | `null`

| `positiveOverruns` | Whether or not overruns should be counted positive rather than negative. | `false`

| `newLinesAsTwoChars` | Whether newlines (`\r`, `\n` and `\r\n`) always be counted as two characters. | `true`

| `postCountMessage` | String shown after character count (e.g. "characters left"). | `null`

| `preCountMessage` | String shown before character count (e.g. "you have"). | `null`

| `postCountMessageSingular` | Same as `postCountMessage` but for the singular case. If not provided, `postCountMessage` will be used. | `null`

| `preCountMessageSingular` | Same as `preCountMessage` but for the singular case. If not provided, `preCountMessage` will be used. | `null`

| `zeroRemainingMessage` | Message shown when 0 characters remain (e.g. "No characters left"). If not set, zero is treated just like any other number. | `null`

| `overrunPostCountMessage` | Same as `postCountMessage` but used once the user has ran over the allocated character count. | `null`

| `overrunPreCountMessage` | Same as `preCountMessage` but used once the user has ran over the allocated character count. | `null`

| `overrunPostCountMessageSingular` | Same as `overrunPostCountMessage` but for the singular case. If not provided, `overrunPostCountMessage` will be used. | `null`

| `overrunPreCountMessageSingular` | Same as `overrunPreCountMessage` but for the singular case. If not provided, `overrunPreCountMessage` will be used. | `null`



### Specifying options



Options can be specified in one of two ways:



 1. Using an object when initialising the plugin

 2. Via data attributes



 Both approaches may be used together but in the event an option is specified both in the options object and as a data attribute, note that the data attribute will take precedence.



#### Via object



You can provide any of the options shown in the table above in an object which should be passed when initialising the plugin.



    $('#example-opts-obj').characterCounter({

        postCountMessage: "characters left",

        postCountMessageSingular: "character left",

        zeroRemainingMessage: "No characters left",

        overrunPreCountMessage: "Please remove",

        overrunPostCountMessage: "characters",

        overrunPostCountMessageSingular: "character",

        positiveOverruns: true

    });



#### Via data attributes



Options can be provided as data attributes on the textarea being initialised. These should all be in the format `data-{option}` where `{option}` is the option name from the table above, lowercased and with words separated with dashes.