parsley.md

   1 ---
   2 title: Parsley.js
   3 updated: 2018-12-06
   4 weight: -1
   5 layout: 2017/sheet
   6 category: JavaScript libraries
   7 keywords:
   8   - "data-parsley-validate"
   9   - "$('#form').parsley()"
  10   - errorClass
  11   - successClass
  12   - classHandler
  13   - errorsContainer
  14   - errorsWrapper
  15   - errorTemplate
  16 intro: |
  17   [Parsley](http://parsleyjs.org/doc/) provides frontend form validation.
  18 ---
  19
  20 ## Parsley
  21 {: .-three-column}
  22
  23 ### Installing via NPM
  24
  25 ```
  26 npm install --save parsleyjs
  27 ```
  28
  29 [parsleyjs](https://www.npmjs.com/package/parsleyjs) is the Parsley form validator. ('parsley' is a different package)
  30
  31 ### Enabling
  32
  33 #### via HTML
  34
  35 ```html
  36 <form data-parsley-validate>
  37 <!-- ✗ not preferred -->
  38 ```
  39
  40 #### via JavaScript
  41
  42 ```js
  43 $('#form').parsley(/* options */)
  44 ```
  45
  46 It's preferable to explicitly call `$.fn.parsley()`.
  47
  48 ### API
  49
  50 #### Form
  51
  52 ```js
  53 $('#myform').parsley()
  54   .isValid()  // → true | null
  55   .validate()
  56   .reset()
  57   .destroy()
  58 ```
  59
  60 #### Input
  61
  62 ```js
  63 $('#myform input').parsley()
  64   .isValid()
  65   .validate() // returns errors
  66 ```
  67
  68 ### Validators
  69
  70 ```html
  71 <input ...>
  72 ```
  73
  74 #### Required
  75
  76 ```html
  77   required
  78 ```
  79
  80 #### Types
  81
  82 ```html
  83   type='email'
  84 ```
  85
  86 ```html
  87   type='url'
  88   data-parsley-type='url'
  89 ```
  90
  91 #### Length
  92
  93 ```html
  94   maxlength='6'
  95   data-parsley-maxlength='6'
  96   minlength='10'
  97   data-parsley-minlength='10'
  98 ```
  99
 100 #### Numeric
 101
 102 ```html
 103   pattern='\d+'
 104   data-parsley-pattern='\d+'
 105 ```
 106
 107 ```html
 108   type='number'
 109   data-parsley-type='number'
 110   data-parsley-type='integer'
 111   data-parsley-type='digits'
 112   data-parsley-type='alphanum'
 113 ```
 114
 115 #### Range
 116
 117 ```html
 118   type='range'
 119   data-parsley=range='[6, 10]'
 120 ```
 121
 122 ```html
 123   max='10'
 124   data-parsley-max='10'
 125   min='6'
 126   data-parsley-min='6'
 127 ```
 128
 129 #### Checkboxes
 130
 131 ```html
 132   data-parsley-mincheck='1'
 133   data-parsley-maxcheck='3'
 134   data-parsley-check='[1, 3]'
 135 ```
 136
 137 #### Confirmation
 138
 139 ```html
 140   data-parsley-equalto='#confirm'
 141 ```
 142
 143 ## Options
 144
 145 ### Form options
 146
 147 ```js
 148 // Supported & excluded inputs by default
 149   inputs: 'input, textarea, select'
 150   excluded: 'input[type=button], input[type=submit], input[type=reset], input[type=hidden]'
 151 ```
 152
 153 ```js
 154 // Stop validating field on highest priority failing constraint
 155   priorityEnabled: true
 156 ```
 157
 158 See: [Options](http://parsleyjs.org/doc/annotated-source/defaults.html)
 159
 160 ### Field options
 161
 162 ```js
 163 // identifier used to group together inputs
 164 // (e.g. radio buttons…)
 165   multiple: null
 166 ```
 167
 168 ```js
 169 // identifier (or array of identifiers) used to
 170 // validate only a select group of inputs
 171   group: null
 172 ```
 173
 174 These options are only available for fields.
 175
 176 ### UI Options
 177
 178 ```js
 179 // Enable/disable error messages
 180   uiEnabled: true
 181 ```
 182
 183 ```js
 184 // Key events threshold before validation
 185   validationThreshold: 3
 186 ```
 187
 188 ```js
 189 // Focused field on form validation error. ‘first’|’last’|’none’
 190   focus: 'first'
 191 ```
 192
 193 ```js
 194 // $.Event() that will trigger validation. eg: keyup, change…
 195   trigger: false
 196 ```
 197
 198 ```js
 199 // Class that would be added on every failing validation
 200 // Parsley field
 201   errorClass: 'parsley-error'
 202   successClass: 'parsley-success'
 203 ```
 204
 205 ```js
 206 // Return the $element that will receive these above
 207 // success or error classes. Could also be (and given
 208 // directly from DOM) a valid selector like '#div'
 209   classHandler: function (ParsleyField) {}
 210 ```
 211
 212 ```js
 213 // Return the $element where errors will be appended.
 214 // Could also be (and given directly from DOM) a valid
 215 // selector like '#div'
 216   errorsContainer: function (ParsleyField) {}
 217 ```
 218
 219 ```js
 220 // ul elem that would receive errors’ list
 221   errorsWrapper: '<ul class="parsley-errors-list"></ul>'
 222 ```
 223
 224 ```js
 225 // li elem that would receive error message
 226   errorTemplate: '<li></li>'
 227 ```
 228
 229 ## Examples
 230
 231 ### Custom container
 232
 233 ```js
 234 $('[data-parsley]').parsley({
 235   errorsContainer (field) {
 236     return field.$element.closest('.block, .control')
 237   }
 238 })
 239 ```
 240
 241 Appends the error to the closest `.block` or `.control`.
 242
 243 ### Custom markup
 244
 245 ```js
 246 $('[data-parsley]').parsley({
 247   errorClass: '-error',
 248   successClass: '-success',
 249
 250   errorsWrapper: '<ul class="parsley-error-list"></ul>',
 251   errorTemplate: '<li class="parsley-error"></li>'
 252 })
 253 ```
 254
 255 Uses custom markup.
 256
 257 ### Custom fields
 258
 259 ```js
 260 $('[data-parsley]').parsley({
 261   classHandler (field) {
 262     const $parent = field.$element.closest('.input-group')
 263     if ($parent.length) return $parent
 264
 265     return field.$element
 266   }
 267 })
 268 ```
 269
 270 Applies the `errorClass` and `successClass` to the closest `.input-group`, if available.
 271
 272 ### Custom validator
 273
 274 #### HTML
 275
 276 ```html
 277 <input type='text' data-parsley-multiple-of='3' />
 278 ```
 279
 280 #### JavaScript
 281
 282 ```js
 283 window.Parsley
 284   .addValidator('multipleOf', {
 285     // string | number | integer | date | regexp | boolean
 286     requirementType: 'integer',
 287
 288     // validateString | validateDate | validateMultiple
 289     validateNumber (value, requirement) {
 290       return 0 === value % requirement
 291     },
 292
 293     messages: {
 294       en: 'This value should be a multiple of %s'
 295     }
 296   })
 297 ```
 298
 299 See: [Custom validators](http://parsleyjs.org/doc/index.html#custom)
 300
 301 ## Also see
 302
 303 - [Parsley documentation](http://parsleyjs.org/doc/) _(parsleyjs.org)_