Parsley.js Documentation & API
Author: Guillaume Potier
Description: Parsley is a dead simple javascript form validation, powerful and UX aware
Keywords: javascript form validation, javascript, form, validation, jquery, plungin, html, UX

### Parsley.js

Parsley 2.0 News

Parsley 2.0 is available in early dev mode for testing purpose.

You can see it there at the moment: Parsley2 doc

Please have a try, and your feeback here would be much appreciated!
Thanks

## Demonstration

Classy demo | HTML Code (yes, no JS !)
--- | ---
Full Name * : Email * : Website : Message (20 chars min, 200 max) : 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"` HTML5`required` HTML5`required="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"` HTML5`type="number" min="6"` | Validates that a given number is greater than some minimum number. |
Max | `parsley-max="100"` HTML5`type="number" max="100"` | Validates that a given number is less than some maximum number. |
Range | `parsley-range="[6, 100]"` HTML5`type="range" min="6" max="100"` | Validates that a given number is between some minimum and maximum number. |
RegExp | `parsley-regexp="<regexp>"` HTML5`pattern="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"` HTML5`type="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"` HTML5`type="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 HTML5`tel` | `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.

- Django
- Rails
- Wicket
- WTForms
- Cascade Framework

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