VERSION NOTICE

This page documents Parsley 1.x versions, which is NOT the latest stable release (2.x versions are). Unless you are here on purpose, you probably want to be viewing the latest documentation.

Go to the latest: parsleyjs.org

Parsley.js

Demonstration

Classy demo HTML Code (yes, no JS !)

Please, note that this demo form is not a perfect example of UX-awareness. The aim here is to show a quick overview of parsley-API and Parsley customizable behavior. 
<form id="demo-form" parsley-validate>
    <label for="fullname">Full Name * :</label>
    <input type="text" name="fullname" required />

    <label for="email">Email * :</label>
    <input type="email" name="email" parsley-trigger="change" required />

    <label for="website">Website :</label>
    <input type="text" name="website" parsley-trigger="change" parsley-type="url" />

    <label for="message">Message (20 chars min, 200 max) :</label>
    <textarea name="message" parsley-trigger="keyup" parsley-rangelength="[20,200]"></textarea>
</form>
Heads up! Le #UX touch:
  • Min char validation: Parsley by default does not proceed with field validation when less than 3 chars have been input. Do not assault your users with error messages too soon! (this behavior is configurable).
  • Quick error removal: when a field is detected and shown as invalid, further checks are done on each keypress to try to quickly remove error messages once the field is ok.
  • Control focusing on error: on form submission, the first error field is focused to allow the user to easily start fixing errors. (this behavior is configurable)

Documentation

  1. Installation & usage: one or two inclusions!
  2. Parsley Form: add some Parsley validation to your forms!
  3. Parsley Field: customize each validated field validation behavior
  4. Validators: learn the various validations you could do with Parsley
    1. Basic constraints
    2. Type constraints
    3. Extra constraints
  5. Javascript: yes, you still can do some javascript with Parsley. Intermediate level only!
    1. General
    2. Form
    3. Fields
  6. Parsley CSS: last but not least, Parsley CSS classes
  7. Plugins & Localization: extend Parsley messages, validators, templates and more!
  8. Integrations: Use parsley from other frameworks.
  9. Support: How to find some useful help about Parsley on the Web..

Parsley Installation

Just include the Parsley.js file (with jQuery or Zepto with data and fx_methods modules added)

<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="parsley.js"></script>

<form parsley-validate>
  [...]
</form>
Heads up! W3C standards: Parsley by default use parsley- API, which is so nice and simple, but absolutely not W3C valid. This is a personal choice, deal with it :) But, if you really want to be W3C compliant, feel free to configure your own DOM-API namespace by overriding Parsley default configs or using data-parsley-namespace="data-parsley-" and use data-parsley-validate to auto bind forms. (see below)
Top

Parsley Form

This is the main Parsley form validation factory, where you decide if a form is validated, and set some extra options.

<form parsley-validate></form>
Heads up! HTML5: If you use HTML5 types and want to disable HTML5 native browser validation, add a novalidate attribute to form tag. If you want to prevent parsley from using any HTML5 validation attributes you can disable it by setting the useHtml5Constraints flag to false in the advanced configuration options, or using parsley-use-html5-constraints="false" in DOM.

Properties

Property Default Description Demonstration
data-parsley-namespace parsley- Choose the DOM-API you want to use for Parsley.
parsley-validate
data-parsley-validate 		Bind Parsley validation to the form and its items with validation constraints
parsley-use-html5-constraints true Bind or not supported HTML5 tags
parsley-show-errors true Choose to show or not Parsley error messages & success / errors classes
parsley-focus first Specify which field will be focused first on form validation errors. first, last and none allowed

parsley-bind The attribute parsley-validate must be used on a form. However, if you want to bind the validation to a DOM element other than a form, just add this attribute. 
<div parsley-validate parsley-bind>
    <input type="text" parsley-type="email" />
</div>
Top

Parsley Field

Once your form is validated by Parsley, add validation constraints and various other options.

<form parsley-validate>
    <input type="text" name="email" parsley-type="email" />
</form>

Properties

Property Default Description Demonstration
parsley-trigger none Specify one or many javascript events that will trigger item validation. eg: parsley-trigger="change". To set multiple events, separate them by a space parsley-trigger="focusin focusout".
See the various events supported by jQuery.

parsley-value Override the value attribute of a form field. Useful for file inputs, where you're not allowed to set a value.
eg: parsley-value="uploadedfile.png"
parsley-validation-minlength 3 Specify how many characters need to be input before the the validation process fires.
eg: parsley-validation-minlength="4"

parsley-error-message Customize a unique global message for this field. Shown if one constraint fails.
eg: 
parsley-type="alphanum" parsley-rangelength="[10,10]"
parsley-error-message="You must enter a 10 characters alphanumeric value"

parsley-error-container Specify here the container where Parsley should set the errors.
eg: 
parsley-error-container="ul#myproperlabel li.someclass"

parsley-`constraintName`-message

parsley-type-`type`-message 		Customize the error message for the field constraint.
eg: parsley-minlength-message="Custom minlength message"

parsley-type-email-message="Custom email message"

Top

Built-in Validators

Name API Description Demonstration

Basic constraints
Required parsley-required="true"

class="required"

HTML5required
HTML5required="required" 		Validate that a required field has been filled.



Radio:
Not Blank parsley-notblank="true" Validates that a value is not blank, defined as not equal to a blank string.
Min Length parsley-minlength="6" Validates that the length of a string is at least as long as the given limit.
Max Length parsley-maxlength="6" Validates that the length of a string is not larger than the given limit.
Range Length parsley-rangelength="[5,10]" Validates that a given string length is between some minimum and maximum value.
Min parsley-min="6"

HTML5type="number" min="6" 		Validates that a given number is greater than some minimum number.
Max parsley-max="100"

HTML5type="number" max="100" 		Validates that a given number is less than some maximum number.
Range parsley-range="[6, 100]"

HTML5type="range" min="6" max="100" 		Validates that a given number is between some minimum and maximum number.
RegExp parsley-regexp="<regexp>"

HTML5pattern="regexp" 		Validates that a value matches a specific regular expression. eg: validate a color hexadecimal code: parsley-regexp="#[A-Fa-f0-9]{6}".

Add a flag to Regexp() function: parsley-regexp-flag="i" for example to make regexp case unsensitive
Equal To parsley-equalto="#elem" Validates that a value is identical to #elem value. Useful for password repeat validation.
Min check parsley-mincheck="2" Validates that a certain minimum number of checkboxes in a group are checked. You can define a group by giving the same name to radio / checkboxes elements or add a parsley-group="mygroup" property to each one of them
Check at least 2 checkboxes:
Max check parsley-maxcheck="2" Validates that a certain maximum number of checkboxes in a group are checked. You can define a group by giving the same name to radio / checkboxes elements or add a parsley-group="mygroup" property to each one of them
Check 2 checkboxes maximum:
Range check parsley-rangecheck="[1,2]" Validates that the number of checked checkboxes in a group is with a certain range. You can define a group by giving the same name to radio / checkboxes elements or add a parsley-group="mygroup" property to each one of them
Check b/w 1&2 checkboxes:
Remote (Ajax) parsley-remote="http://yoururl.com" Custom ajax validation made simple.
parsley-remote-method="POST" to change default GET call.
parsley-remote-datatype="jsonp" if you make cross domain ajax call and expect jsonp
Parsley will accept these valid returns with a 200 response code: 1, true, { "success": "..." } and assume false otherwise
You can show frontend server-side specific error messages by returning { "error": "your custom message" } or { "message": "your custom message" }

Type Constraints
Email parsley-type="email"

HTML5type="email" 		Validates that a value is a valid email address.
Url parsley-type="url" type="url" Validates that a value is a valid url.
Url strict parsley-type="urlstrict" Validates that a value is a valid strict URL, ie: with one of http, https, ftp, git allowed protocols.
Digits parsley-type="digits" Validates that a value is only digits.
Number parsley-type="number"

HTML5type="number" 		Validates that a value is a valid number.
Alphanum parsley-type="alphanum" Validates that a value is a valid alphanumeric string.
Date Iso parsley-type="dateIso" Validates that a value is a valid ISO date.
Phone HTML5tel
 parsley-type="phone" Validates that a value is a valid phone number.

Extra Validators

There are some extra validators, not shipped along with default Parsley, because they're more specific and less common, and there is no need to add weight to Parsley instead of calling these validators only when needed. Just call parsley.extend.js or dist/parsley.extend.min.js like this: 

<script type="text/javascript" src="parsley.extend.fr.js"></script>
<script type="text/javascript" src="parsley.js"></script>
Please, feel free to fork and contribute by adding some useful validators!


Here is the list of parsley.extra validators
Name Api Description
Min Words parsley-minwords="6" Validate that a field has at least 6 words.
Max Words parsley-maxwords="6" Validate that a field has 6 words maximum.
Range Words parsley-rangewords="[6,10]" Validate that a field has between 6 and 10 words.
Greater Than parsley-greaterthan="#elem" Validate that a field's value is greater than #elem's value.
Less Than parsley-lessthan="#elem" Validate that a field's value is lower than #elem's value.
Before date parsley-beforedate="#elem" Validate that a field's date is before #elem's date.
On or before date parsley-onorbeforedate="#elem" Validate that a field's date is on or before #elem's date.
After date parsley-afterdate="#elem" Validate that a field's date is after #elem's date.
On or after date parsley-onorafterdate="#elem" Validate that a field's date is on or after #elem's date.
In list parsley-inlist="foo, bar, foo bar" Validates that a field's value is present within the value list. You can define the delimiter using parsley-inlist-delimiter=",". Delimiter defaults to ",".
Luhn parsley-luhn="true" Validates that a fields value passes the Luhn algorithm. Validates credit card numbers, as well as some other kinds of account numbers.
American Date parsley-americandate="true" Validates that a value is a valid American Date. Allows for slash, dot and hyphen delimiters and condensed dates (e.g., M/D/YY MM.DD.YYYY MM-DD-YY).
Top

Javascript

Parsleys DOM-API is great. But not so great for complex forms, or dynamically generated forms. Learn how to master Parsley javascript style!

Warning : you must remove parsley-validate auto-binding code in your forms DOM to allow you to override the default processing and use Parsley purely from javascript.

Method Returns Description Code

General
Override default plugin configs Parsley uses a set of default configs that you can override by passing an object as a parameter when calling Parsley on a form or a field.
Default is: 
{
  // basic parsley-api overridable properties here..
  inputs: 'input, textarea, select'
  , excluded: 'input[type=hidden]'
  , trigger: false
  , animate: true
  , focus: 'first'
  , validationMinlength: 3
  , successClass: 'parsley-success'
  , errorClass: 'parsley-error'
  , validators: {}
  , showErrors: true
  , useHtml5Constraints: true
  , messages: {}

  //some quite advanced configuration here..
  , validateIfUnchanged: false
  , errors: {                     // specify where parsley error-success classes are set
    classHandler: function ( elem, isRadioOrCheckbox ) {}
  , container: function ( elem, isRadioOrCheckbox ) {}
  , errorsWrapper: '<ul></ul>'
  , errorElem: '<li></li>'
  }
  , listeners: {
      onFieldValidate: function ( elem, ParsleyField ) { return false; }
    , onFormValidate: function ( isFormValid, event, ParsleyForm ) {}
    , onFieldError: function ( elem, constraints, ParsleyField ) {}
    , onFieldSuccess: function ( elem, constraints, ParsleyField ) {}
  }
}

Add a custom validator that checks if number is a multiple of another:

$( '#form' ).parsley( {
    validators: {
      multiple: function() {
        return {
          validate: function(val, multiple) {
            return val % multiple === 0;
          },
          priority: 2
        };
      }
    }
  , messages: {
      multiple: "This value should be a multiple of %s"
    }
} );
<input type="text" parsley-multiple="3" />
Add a listener Allows you, even after Parsleys initial form binding, to add a custom listener. Available listeners currently are: onFieldValidate, onFieldError, onFieldSuccess and onFormValidate. Their passed arguments are listed above in Default Plugin config. Note that if onFormValidate callback returns false, form won't be submitted, even if Parsley valid. It allows you to add another custom check on top of Parsley. Similarly, if onFieldSuccess returns false, field would be considered as invalid and form too. 
$( '#form' ).parsley( 'addListener', {
    onFieldValidate: function ( elem ) {

        // if field is not visible, do not apply Parsley validation!
        if ( !$( elem ).is( ':visible' ) ) {
            return true;
        }

        return false;
    }
} );

Form
Bind Parsley to a form Useful if your form is dynamically rendered. 
$( '#form' ).parsley();
Validate a form Boolean Useful if you want to integrate the form validation process inside custom functions. 
$( '#form' ).parsley( 'validate' );
Test if form valid Boolean Useful if you want to integrate the form validation process inside custom functions, without triggering error messages. 
$( '#form' ).parsley( 'isValid' );
Destroy Parsley Reset error messages, error classes, stop prevent form submission and validation triggered events. 
$( '#form' ).parsley( 'destroy' );
Dynamically add an Item to Form If an item is dynamically created, it won't be naturally validated with Parsley. Use this to attach it to existing Parsley validated form. 
$( '#form' ).parsley( 'addItem', '#itemid' );
Dynamically remove an Item to Form If an item is dynamically deleted / removed from form, it will be unfortunately still present in Parsley validation process. Use this to remove it in Parsley form validation process. This field must have an id to be properly destroyed 
$( '#form' ).parsley( 'removeItem', '#itemid' );

Field
Validate a field Boolean Useful if your want to integrate the field validation process inside custom functions. 
$( '#field' ).parsley( 'validate' );
Add new constraint Useful if your want to add a constraint to an existing Parsley validated field. 
$( '#field' ).parsley( 'addConstraint', { minlength: 2 } );
Update constraint Useful if your want to update an existing constraint for a field. 
$( '#field' ).parsley( 'updateConstraint', { minlength: 6 } );
Remove constraint Useful if your want to remove an existing constraint to an existing Parsley validated field. 
$( '#field' ).parsley( 'removeConstraint', 'minlength' );

More generally, in the Parsley API: All ParsleyForm and ParsleyItem functions can be publicly called using the following syntax: 

$( '#parsleyFormOrFieldId' ).parsley( 'functionName', parameter );
So help yourself, read the code and play with Parsley! ;)

Top

Parsley CSS

A good #UX goes with a good #UI. Parsley has some base classes you can use to customize things a bit ;) (and of course, rename in the configuration object)

Class Description
Default classes & templates
.parsley-validated Auto added on each form item that has Parsley validation.
.parsley-success Auto added on each form item that has successfully passed validation.
.parsley-error Auto added on each form item that did not pass Parsley validation.
ul.parsley-error-list Auto added after each form item that did not pass Parsley validation. Container for errors <li>.
li.parsley-error Message displayed if constraint failed validation.
Override them!
Change class names 
$('#form').parsley({ successClass: 'my-class-name', errorClass: 'still-my-class-name' });
Change class handler Add parsley-success and parsley-error to direct parent: 
$('#form').parsley( {
    errors: {
        classHandler: function ( elem, isRadioOrCheckbox ) {
            return $( elem ).parent();
        }
    }
} );
Change error container

Override the container that the errorWrapper (ie. by default the <ul></ul> containing the errors) is inserted into.

By default this function does not return anything and so the errorWrapper is added to the DOM directly after the element containing the error, however if you override this function in your options you can return an alternative container where the errorWrapper will be appended

For example, to have the error messages appear before the field with the error in a div with the class .parsley-container:

errors: {
    container: function (element, isRadioOrCheckbox) {
        var $container = element.parent().find(".parsley-container");
        if ($container.length === 0) {
            $container = $("<div class='parsley-container'></div>").insertBefore(element);
        }
        return $container;
    }
}

Advanced changes See errorsWrapper, errorElem errors properties in Parsley default options.
Top

Parsley Plugins & Localization

Parsley is shipped with localization (i18n) for its failure messages, and with extra, advanced validators, not included in parsley by default. Learn how to use them here.

Localizations

Here are Parsleys error messages in various supported languages. To use one of these, just call the desired language file. Eg: for French messages: 

<script type="text/javascript" src="/i18n/messages.fr.js"></script>
<script type="text/javascript" src="parsley.js"></script>
Please, feel free to fork and contribute by adding your own translations messages in your language!


Integration with other frameworks

There is a growing community of tools integrating Parsley with other frameworks. If you create such a tool, please submit a pull request.

Top

Parsley support

There are plenty master tricks for Parsley out there. Please, have a look to Stackoverflow Parsley related questions for more info. If you find a real bug, then feel free to open a Github issue, with bug description and if possible a live example (jsfiddle, self hosted, pastebin..) to help us spot and fix it. Thanks.

Top

© @guillaumepotier @Wisembly 2012 - Ever heard of #Garlic.js, Parsley little sister?