Referee JS

Add simple maximum and minimum input length indicators to your fields in a few seconds.

The input max/min length indicator uses javascript to display a warning message on top of an input field when the user has not yet entered the minimum or maximum character restrictions specified.

Demo/Examples

Show minimum and maximum length warnings

In this example the field will warn against any input less than 4 or greater than 40:

Code:


        <input type="email" data-referee="true" 
             data-referee-display-on-init="true"
             data-min-length="4" data-max-length="40" class="form-control" 
             placeholder="Enter email between 4-40 characters.">

Customize the Remaining Characters Template

In this example the field will warn against any input less than 8 characters with a custom template.

Code:


        <input type="password" class="form-control" 
             data-referee="true" data-min-length="8"
             data-referee-display-on-init="true"
             data-referee-min-template="{{charRemain}} more character{{s}} for a good password"
             placeholder="Enter password more than 8 characters.">

Show Characters Left With Maximum

In this example the field will warn you once you are getting close to the maximum number of characters.

Code:


        <input type="text" class="form-control" 

            placeholder="Enter Company Name (Max 20 Characters)" 

            data-referee="true" 

            data-max-length="20" 

            data-referee-chars-left-threshold="5"

            data-referee-display-on-init="true">

Only Show Characters Left (Twitter Style)

You can use the data-referee-always-show-count attribute to always show the character count. This overrides other settings.

Code:


        <input type="text" class="form-control" 

            placeholder="Enter Company Name (Max 20 Characters)" 

            data-referee="true" 

            data-max-length="40" 

            data-referee-always-show-count="true" 

            data-referee-warning-threshold="20" 

            data-referee-display-on-init="true">

Installation

To install simply include the dist/refereejs.js and dist/refereejs.css files in your project.

To install with bower simply run this from your console:
bower install refereejs --save. Then include the dist/refereejs.js and dist/refereejs.css files in your project.

Requirements

jQuery 1.8 or higher

Usage

To use the indicator simply add the data-referee attribute to your input element, then specify a data-min-length="123" attribute to warn against min/max lengths.

That simple! The JS will attach events on page load.

Dynamically Generated Content

If you're dynamically generating content using JS (ie Angular) then you will need to run $('#id_of_your_input').referee();.

Customization

Data Attributes

data-referee	Enables the min/max indicator on an input element. Note: Until you set this attribute the indicator won't run. Default: undefined (false)
data-min-length	Indicate what the minimum length is. If left blank then no minimum warning will be shown. Default: undefined
data-max-length	Indicate what the maximum length is. If left blank then no maximum warning will be shown. Default: undefined
data-referee-min-template	What template to use when when displaying the minimum length warning. Default: `{{charRemain}} too few characters (min: {{min}})`.
data-referee-max-template	What template to use when when displaying the maximum length warning. Default: `too many characters ({{currLength}}/{{max}})`.
data-referee-chars-left-threshold	How many characters before the maximum to show the characters left warning. If not specified then no warning will be shown. Default: undefined
data-referee-chars-left-template	What template to use when when displaying the characters left warning. Default:: `({{charRemain}} character{{s}} left`.
data-referee-display-on-init	If set to "true" will show warning messages on initialization. That is, if a value is already in the field then it will show a message when the page loads or the indicator is initialized. Otherwise it will wait for user input before showing any messages. Default: false
data-referee-always-show-count	If enabled then this will always show the number of characters left on the top right of the input. Also see `data-referee-warning-threshold` to set a color change threshold. Default: false
data-referee-warning-threshold	When the # characters left hits this number the `warning-threshold` class will be added which by default shows a different (orange) color than the standard grey character count color. Default: 25% of max length

Customizing Templates

You can customize the displayed templates easily by setting the template options. Here are the variables that you can use in your templates:

{{max}} - Maximum characters allowed as configured.
{{min}} - Minimum characters allowed as configured.
{{charRemain}} - Characters remaining to hit minimum or maximum (depending on the template).
{{currLength}} - Current string length of input entry.
{{s}} - Gets replaced with an empty string ('') if {{charRemain}} == 1 and replaced with 's' otherwise. This is useful for displaying pluralized strings in your template. For example You have {{charRemain}} letter{{s}} over limit) would display "1 letter left" when the user is 1 character over the character limit.

Customizing Styles

See the included CSS. It's pretty simple to customize the css styles by defining your own CSS classes.

Contribution

If you'd like to contribute to the repo that's great! Simply fork the repo and open up a pull request against it.