jQuery Password Strength Meter for Twitter Bootstrap

The jQuery Password Strength Meter is a plugin for Twitter Bootstrap that provides rulesets for visualy displaying the quality of a users typed in password.

Dual licensed under the MIT and GPL licenses.

jQuery plugins registry entry

Requirements

• jQuery 1.7 or higher
• Bootstrap 2 or 3

How to use it

Just invoke the plugin on the password fields you want to attach a strength meter to. For example, to use it on all the password fields with the default examples:

    $(':password').pwstrength();

To apply it only to one input and change the options:

    $('#passwd1').pwstrength({
        ui: { showVerdictsInsideProgressBar: true }
    });

Options

The plugin expect the options to follow this structure:

options = {
    common: {},
    rules: {},
    ui: {}
};

Let's see the options of each section.

Common

• minChar:

  Default: 6 (Integer)

  Sets the minimum required of characters for a password to not be considered too weak.

• usernameField:

  Default: "#username" (String)

  The username field to match a password to, to ensure the user does not use the same value for their password.

• userInputs:

  Default: [] (Array)

  Array of CSS selectors for input fields with user input. The content of these fields will be retrieved and passed to the zxcvbn library.

  This option only takes effect when the zxcvbn library is being used. Check the zxcvbn option.

• onLoad:

  Default: undefined (Function)

  A callback function, fired on load of the widget. No arguments will be passed.

• onKeyUp:

  Default: undefined (Function)

  A callback function, fired on key up when the user is typing. The keyup event will be passed as first argument, and an object as second with the score and the verdict text and level.

  This handler will also be called when the change or the onpaste events happen.

• zxcvbn:

  Default: false (Boolean)

  Use the zxcvbn to calculate the password entropy and use it as the score. For more information about zxcvbn plase check this post.

  If you activate this setting, then all the rules won't be applied, and all the options under the Rules section will be ignored as well. zxcvbn will be used instead of the default rules engine.

  To use this option you must load the zxcvbn library file on your site. You'll find it at their repository.

• debug:

  Default: false (Boolean)

  If true, it prints the password strength in the javascript console, so you can test and tune your rules settings.

Rules

• extra:

  Default: {} (Object)

  Empty object where custom rules functions will be stored.

• scores:

  Default: (Object)

  {
    wordNotEmail: -100,
    wordLength: -50,
    wordSimilarToUsername: -100,
    wordSequences: -50,
    wordTwoCharacterClasses: 2,
    wordRepetitions: -25,
    wordLowercase: 1,
    wordUppercase: 3,
    wordOneNumber: 3,
    wordThreeNumbers: 5,
    wordOneSpecialChar: 3,
    wordTwoSpecialChar: 5,
    wordUpperLowerCombo: 2,
    wordLetterNumberCombo: 2,
    wordLetterNumberCharCombo: 2
  }
  

  Scores returned by the rules when they match. Negative values are for penalizations.

• activated:

  Default: (Object)

  {
    wordNotEmail: true,
    wordLength: true,
    wordSimilarToUsername: true,
    wordSequences: true,
    wordTwoCharacterClasses: false,
    wordRepetitions: false,
    wordLowercase: true,
    wordUppercase: true,
    wordOneNumber: true,
    wordThreeNumbers: true,
    wordOneSpecialChar: true,
    wordTwoSpecialChar: true,
    wordUpperLowerCombo: true,
    wordLetterNumberCombo: true,
    wordLetterNumberCharCombo: true
  }
  

  An object that sets wich validation rules are activated. By changing this object is possible to deactivate some validations, or to activate them for extra security.

• raisePower:

  Default: 1.4 (Double)

  The value used to modify the final score, based on the password length, allows you to tailor your results.

User Interface

• bootstrap2:

  Default: false (Boolean)

  Sets if it supports legacy Bootstrap 2 (true) or the current Bootstrap 3 (false), the progress bar html is different.

• showProgressBar:

  Default: true (Boolean)

  Displays the password strength in a progress bar.

• showPopover:

  Default: false (Boolean)

  Displays the error messages and the verdicts in a Bootstrap popover, instead of below the input field. Bootstrap tooltip.js and popover.js must to be included.

  If the showVerdictsInsideProgressBar option is active, then the verdicts won't appear on the popover.

• showStatus:

  Default: false (Boolean)

  Displays the password strength as a validation status in the password field, for this to work, the Bootstrap form structure must be followed.

• spanError:

  Default: (Function)

  function (options, key) {
    var text = options.ui.errorMessages[key];
    return '<span style="color: #d52929">' + text + '</span>';
  };

  Function to generate a span with the style property set to red font color, used in the errors messages. Overwrite for custom styling.

• popoverError:

  Default: (Function)

  function (errors) {
    var message = "<div>Errors:<ul class='error-list' style='margin-bottom: 0;'>";
    jQuery.each(errors, function (idx, err) { message += "<li>" + err + "</li>"; });
    message += "</ul></div>";
    return message;
  };

  Function to generate the errors list in the popover if showPopover is true. Overwrite for custom styling.

• errorMessages:

  Default: (Object)

  {
    wordLength: "Your password is too short",
    wordNotEmail: "Do not use your email as your password",
    wordSimilarToUsername: "Your password cannot contain your username",
    wordTwoCharacterClasses: "Use different character classes",
    wordRepetitions: "Too many repetitions",
    wordSequences: "Your password contains sequences"
  }
  

  An object containing error messages. These can be overwritten for language purposes, and extra messages can also be added for other rules, existing or custom. Use the name of the rule as key.

• verdicts:

  Default: ["Weak", "Normal", "Medium", "Strong", "Very Strong"] (Array)

  The display names for the verdicts related to the progressClass. It has to have 5 elements, and they would be the 5 possible strength categories.

• showVerdicts:

  Default: true (Boolean)

  Determines if the verdicts are displayed or not.

• showVerdictsInsideProgressBar:

  Default: false (Boolean)

  Determines if the verdicts are displayed inside the progress bar or not. When this setting is active, the verdict viewport is ignored and they won't appear on the popover if it is being showed. Also this option overrides the value of the showVerdicts one.

• showErrors:

  Default: false (Boolean)

  Determines if the error list is displayed with the progress bar or not.

• container:

  Default: undefined (CSS selector, or DOM node)

  If defined, it will be used to locate the viewports, if undefined, the parent of the input password will be used instead. The viewports must be children of this node.

• viewports:

  Default: (Object)

  {
    progress: undefined,
    verdict: undefined,
    errors: undefined
  }
  

  An object containing the viewports to use to show the elements of the strength meter. Each one can be a CSS selector ("#progressbar") or a DOM node reference.

• scores:

  Default: [17, 26, 40, 50] (Array)

  The scores used to determine what progressClass and verdicts to display. It has to have 4 elements, which creates 5 categories of strength (the 5 possible verdicts).

Example of an options object

var options = {};
options.common = {
    minChar: 8;
};
options.rules = {
    activated: {
        wordTwoCharacterClasses: true,
        wordRepetitions: true
    }
};
options.ui = {
    showErrors: true
};

Methods

Once the plugin has been initialized, it is possible to interact with it through the methods.

Force an update

It is possible to force an update on a password strength meter. It will force a new score calculation and an update of the UI elements, the onKeyUp callback will be called.

$("#passwdfield").pwstrength("forceUpdate");

Remove the strength meter

This will remove the data associated to the meter, and the UI elements.

$("#passwdfield").pwstrength("destroy");

Adding Custom Rules

The plugin comes with the functionality to easily define your own custom rules. The format is as follows:

$("#passwdfield").pwstrength("addRule", "ruleName", function (options, word, score) {}, rule_score, rule_enabled);

Example:

$("#passwdfield").pwstrength("addRule", "testRule", function (options, word, score) {
    return word.match(/[a-z].[0-9]/) && score;
}, 10, true);

Change the score associated to a rule

It is possible to change the score given by a rule. It works like this:

$("#passwdfield").pwstrength("changeScore", "wordSequences", -100);

That would penalize even more the presence of sequences in the password.

Activate and deactivate rules

It is also possible to activate or deactivate rules. It as simple as:

$("#passwdfield").pwstrength("ruleActive", "wordSequences", false);

That would avoid looking for sequences in the password being tested.

Callback Functions

The plugin provides two callback functions, onLoad and onKeyUp. You can use them like this:

$(document).ready(function () {
    var options = {};
    options.common = {
        onLoad: function () {
            $('#messages').text('Start typing password');
        },
        onKeyUp: function (evt, data) {
            $("#length-help-text").text("Current length: " + $(evt.target).val().length + " and score: " + data.score);
        }
    };
    $(':password').pwstrength(options);
});

Extra security

The plugin comes with two validation rules deactivated by default. One checks for too many character repetitions, and the other checks the number of character classes used. An easy way to increase the security of the passwords is to activate this two rules:

$(document).ready(function () {
    var options = {};
    options.rules = {
        activated: {
            wordTwoCharacterClasses: true,
            wordRepetitions: true
        }
    };
    $(':password').pwstrength(options);
});

Examples

There are some examples in the examples directory. Just serve them with any webserver and check them in your browser. Make sure you serve the examples directory as the site root. For example:

cd examples
python -m SimpleHTTPServer

And go to localhost:8000.

Build and Test

The build and testing processes rely on Grunt. To use them you need to have node.js and grunt-cli installed on your system. Assuming you have node.js in your Linux system, you'll need to do something like this:

sudo npm install -g grunt-cli

Now you have the grunt command line utility installed globally.

Bundle and minified

To generate the bundle and the minified file you only need to execute this in the project directory:

npm install -d
grunt

It will check the source files, and build a minified version with its corresponding source map. The generated files will be available in the dist directory.

Testing

To run the tests the only thing you need to do is execute this in the project directory:

npm install -d
grunt test

It will check all the source files with JSLint and run the tests, which are written with Jasmine. You'll find the tests source code in the spec directory.

Travis is being used for continuos integration. You can check there if the tests are passing.