Configuration

Everything below is passed to $.validate(). This is the complete list as it stands in the source.

JavaScript

$.validate({
  form: '#checkout',
  modules: 'security, date',
  errorMessagePosition: 'top',
  bootstrap: 5,
  onSuccess: function ($form) { return true; }
});

Setup

Option	Default	Description
`form`	`'form'`	Selector for the form or forms to set up.
`modules`	`''`	Comma separated modules to load. Modules already registered by an `import` are not fetched again.
`lang`	—	Language code to load from `lang/`, e.g. `'sv'`.
`language`	`false`	Object overriding individual messages. See Localization.
`ignore`	`[]`	Names of inputs to skip even when they carry validation rules.
`novalidate`	`true`	Add `novalidate` to the form so the browser does not stack its own bubbles on top of the plugin's messages. A `novalidate` you wrote yourself is never removed.
`observeDynamicFields`	`false`	Watch the form with a `MutationObserver` and wire up fields added after `$.validate()` ran.
`preferNativeValidation`	`false`	With the `native` module loaded, let the browser answer `type`, `min`, `max`, `step` and `pattern`.
`validateHiddenInputs`	`false`	Whether hidden inputs are validated.
`bootstrap`	`false`	Which Bootstrap release the page uses, so matching class names are emitted. See below.

When validation runs

Option	Default	Description
`validateOnBlur`	`true`	Validate a field when it loses focus.
`validateOnEvent`	`false`	Honour `data-validation-event` on an element.
`validateCheckboxRadioOnClick`	`true`	Validate checkboxes and radios as soon as they are clicked.
`showHelpOnFocus`	`true`	Fade in `data-validation-help` text on focus.
`addSuggestions`	`true`	Enable the input suggestion feature.

HTML

<!-- With validateOnEvent: true -->
<input data-validation="required" data-validation-event="change">

Error presentation

Option	Default	Description
`errorMessagePosition`	`'inline'`	`'inline'` writes each message beside its field; `'top'` renders one summary above the form.
`errorMessageTemplate`	see below	Markup used to build the summary.
`errorMessageClass`	`'form-error'`	Class on the element holding a message. This is the plugin's own hook for finding its messages — read the note under Bootstrap presets before changing it.
`inlineErrorMessageClass`	`'help-block'`	Extra class on an inline message, for your CSS framework. `'invalid-feedback'` under `bootstrap: 4`/`5`.
`helpTextClass`	`'help-block'`	Extra class on `data-validation-help` text. `'form-text'` under `bootstrap: 4`/`5`.
`errorElementClass`	`'error'`	Class applied to an invalid field.
`successElementClass`	`'valid'`	Class applied to a field that validated.
`addValidClassOnAll`	`false`	Apply `successElementClass` even to fields that were never validated.
`inputParentClassOnError`	`'has-error'`	Class on the invalid field's parent.
`inputParentClassOnSuccess`	`'has-success'`	Class on the valid field's parent.
`borderColorOnError`	`'#b94a48'`	Inline border colour for an invalid field. An empty string leaves the border alone.
`scrollToTopOnError`	`true`	Scroll to the summary on a failed submit.
`focusOnError`	`true`	Move focus to the summary, or the first invalid field, on a failed submit. See Accessibility.
`inlineErrorMessageCallback`	`false`	`function($input, errorMsg, conf)` returning the element the inline message should be written into. Return something falsy to suppress the plugin's own display entirely.
`submitErrorMessageCallback`	`false`	`function($form, errorMessages, conf)` returning the container for the summary. Return something falsy to handle display yourself.

Parsing

Option	Default	Description
`validationRuleAttribute`	`'data-validation'`	Attribute holding the rules.
`validationErrorMsgAttribute`	`'data-validation-error-msg'`	Attribute holding a per-field custom message.
`dateFormat`	`'yyyy-mm-dd'`	Format used by `date` and `birthdate`.
`decimalSeparator`	`'.'`	Set to `'auto'` to take it from the browser locale. See Numbers.

Callbacks

Option	Signature	Description
`onModulesLoaded`	`function()`	Called once every module named in `modules` has registered.
`onSuccess`	`function($form)`	On a passing submit. Return `false` to stop the submission — useful when you want to post over XHR.
`onError`	`function($form)`	On a failing submit.
`onElementValidate`	`function(valid, $input, $form, errorMsg)`	After each individual field is validated.

JavaScript

$.validate({
  onSuccess: function ($form) {
    $.post('/signup', $form.serialize());
    return false;   // we are handling the submit ourselves
  },
  onError: function ($form) {
    analytics.track('signup_validation_failed');
  },
  onElementValidate: function (valid, $input, $form, errorMsg) {
    if (!valid) {
      console.log($input.attr('name') + ': ' + errorMsg);
    }
  }
});

Bootstrap presets

The class names this plugin has emitted since 2.x are Bootstrap 3 vintage: has-error on the field's parent, help-block on the message. Bootstrap 4 removed every one of them and validates instead through is-invalid on the control itself, with a sibling .invalid-feedback carrying the text. Bootstrap 5 kept that model.

Tell the plugin which release you are on and it emits the right names:

JavaScript

$.validate({ bootstrap: 5 });   // 3, 4, 5, or a full version like '5.3.2'

Option	Default	Under `bootstrap: 4` / `5`
`errorElementClass`	`'error'`	`'is-invalid'`
`successElementClass`	`'valid'`	`'is-valid'`
`inlineErrorMessageClass`	`'help-block'`	`'invalid-feedback'`
`helpTextClass`	`'help-block'`	`'form-text'`
`inputParentClassOnError`	`'has-error'`	`''` — no longer exists
`inputParentClassOnSuccess`	`'has-success'`	`''` — no longer exists
`borderColorOnError`	`'#b94a48'`	`''` — so Bootstrap's own palette wins

Your own options still win

The preset is layered between the defaults and the configuration you pass, so anything you state explicitly beats it. {bootstrap: 5, errorElementClass: 'my-error'} uses your class.

<code>errorMessageClass</code> keeps its default on purpose

It is the hook the plugin uses to find, update and remove its own messages, and Bootstrap has no class that plays that role — invalid-feedback is presentation only. So the Bootstrap class is added alongside it rather than replacing it. Replacing it would also hide the error summary, because .invalid-feedback stays display: none until an .is-invalid sibling reveals it — which a summary at the top of a form never has.

Customising the summary

errorMessageTemplate builds the errorMessagePosition: 'top' summary. Override any subset of its keys; whatever you leave out falls back to the default.

JavaScript

$.validate({
  errorMessagePosition: 'top',
  errorMessageTemplate: {
    container: '<section class="{errorMessageClass}" role="alert">{messages}</section>',
    messages: '<h2>{errorTitle}</h2><ol>{fields}</ol>',
    field: '<li><a href="#{id}">{msg}</a></li>',
    fieldNoLink: '<li>{msg}</li>'
  }
});

Placeholder	Available in	Meaning
`{errorMessageClass}`	`container`	The configured `errorMessageClass`.
`{messages}`	`container`	The rendered `messages` template.
`{errorTitle}`	`messages`	The `errorTitle` language string.
`{fields}`	`messages`	The rendered `field` templates, concatenated.
`{msg}`	`field`, `fieldNoLink`	The validation message.
`{id}`	`field`	The id of the field, generated if it has none — this is what makes the summary navigable.

Substitution is single pass

A validation message that happens to contain something like {fields} is inserted literally rather than being treated as a placeholder.

Taking over display entirely

For full control, return your own container from a callback — or return something falsy to suppress the plugin's rendering and do it all yourself.

JavaScript

$.validate({
  inlineErrorMessageCallback: function ($input, errorMsg, conf) {
    // Write the message wherever your layout wants it…
    return $input.closest('.field').find('.field-error');
  },

  submitErrorMessageCallback: function ($form, errorMessages, conf) {
    myToast.show(errorMessages);
    return false;   // nothing rendered by the plugin
  }
});

Per-field attributes

Configuration also happens in the markup. These apply to any field, whatever rules it carries.

Attribute	Effect
`data-validation`	The rules, space separated.
`data-validation-optional="true"`	Only validate when a value has been entered.
`data-validation-error-msg`	Custom message for this field.
`data-validation-error-msg-rule`	Custom message for one specific rule.
`data-validation-help`	Help text shown while the field has focus.
`data-validation-error-msg-container`	Selector for where this field's message should be written.
`data-validation-event`	Validate on this event, with `validateOnEvent: true`.
`data-validation-ignore`	Characters stripped from the value before validating.
`data-suggestions`	Comma separated suggestions offered as the user types.
`data-sanitize`	Sanitizers to run first. Needs the `sanitize` module.

HTML

<input name="phone"
       data-validation="required"
       data-validation-ignore=" -()"
       data-validation-help="Digits only; spaces and dashes are fine"
       data-validation-error-msg="We need a phone number">