Clientside Validation
Adds client-side form validation to Drupal forms using data attributes and the jQuery Validation Plugin.
clientside_validation
Install
composer require 'drupal/clientside_validation:^4.1'
Overview
Clientside Validation is a module that provides instant, client-side form validation for Drupal forms before server submission. The module works by adding HTML5 data attributes to form elements, which are then processed by a JavaScript validation library.
The module consists of a core base module and a jQuery submodule. The core module handles the PHP side of adding data-rule-* and data-msg-* attributes to form elements based on their validation requirements. The clientside_validation_jquery submodule integrates the popular jQuery Validation Plugin to perform the actual client-side validation.
The module supports various validation types including required fields, email validation, URL validation, numeric range validation (min, max, step), pattern matching, and field equality checks. It also integrates seamlessly with Drupal's States API for conditional validation, CKEditor for WYSIWYG fields, and the Inline Form Errors module for consistent error display.
Features
- Automatic client-side validation for all Drupal forms without additional configuration
- Plugin-based architecture allowing custom validators through the CvValidator plugin system
- Built-in validators for required, email, URL, min, max, step, maxlength, and pattern validation
- Support for conditional required fields using Drupal's States API (#states)
- Custom error messages via #required_error, #email_error, #url_error, #min_error, #max_error, #step_error, #maxlength_error, and #pattern_error form element properties
- Equal-to validation for password confirmation and similar field matching scenarios
- AJAX form validation support with configurable behavior
- CKEditor integration for validating WYSIWYG editor content
- Inline Form Errors module integration for consistent error styling
- Flexible library loading via CDN or local installation
- Drush commands for managing the jQuery Validation library
- Hook system for controlling validation behavior and extending functionality
Use Cases
Basic Required Field Validation
Add the #required property to any form element to automatically get client-side required validation. The module will display an error message like 'Field name field is required.' when the user tries to submit without filling the field. Customize the message using #required_error property.
Password Confirmation Validation
Use the #equal_to property to validate that a confirmation field matches another field. For example, add '#equal_to' => 'pass1' to a password confirmation field to ensure it matches the original password field named 'pass1'. Customize the error message with #equal_to_error.
Pattern-Based Validation
Use the #pattern property with a regular expression to validate field formats like phone numbers, postal codes, or custom identifiers. Example: '#pattern' => '[789][0-9]{9}' for Indian phone numbers. Customize the error message with #pattern_error.
Numeric Range Validation
Use #min, #max, and #step properties on number fields to validate numeric constraints. For example, age fields can use '#min' => 18, '#max' => 120, and quantity fields can use '#step' => 5 to allow only multiples of 5.
AJAX Form Validation
Enable 'Validate all forms before AJAX submit' in settings or add the CSS class 'cv-validate-before-ajax' to specific forms to validate fields before AJAX form submissions occur, preventing unnecessary server requests.
Conditional Required Fields with States API
Combine Drupal's #states API with client-side validation for conditional required fields. Example: '#states' => ['required' => [':input[name="option"]' => ['value' => 'other']]] will make a field required only when another field has a specific value.
Creating Custom Validators
Extend the module by creating CvValidator plugins in your custom module. Place the plugin class in src/Plugin/CvValidator/ with the @CvValidator annotation specifying supported types/attributes. Implement getRules() to return validation rules and messages.
Tips
- Use the demo module (clientside_validation_demo) to test all validation features and see working examples of form element configurations.
- For better user experience, enable 'Validate on Blur/focusout' in settings to provide immediate feedback as users tab through form fields.
- When creating custom validators, implement hook_clientside_validation_validator_info_alter() to attach any additional JavaScript libraries your validator requires.
- The module automatically supports Drupal's stream wrappers (public://, private://) in URL validation, allowing valid file references.
- Use hook_clientside_validation_should_validate() to selectively disable validation for specific forms or elements that require special handling.
- Custom JavaScript can listen to the 'cv-jquery-validate-options-update' event on document to modify jQuery Validation options globally.
- For forms with formnovalidate attribute on submit buttons, client-side validation will be skipped, useful for 'Cancel' or 'Save as Draft' buttons.
Technical Details
Admin Pages 2
/admin/config/user-interface/clientside-validation-jquery-settings
Configure how the jQuery Validation Plugin is loaded and how validation behaves on forms. This page allows administrators to choose between CDN and local library loading, configure AJAX form validation behavior, and enable additional validation features.
/admin/config/user-interface/clientside-validation-demo
A demonstration form that showcases all the validation capabilities of the Clientside Validation module. This form includes examples of required fields, custom error messages, conditional required fields, email validation, URL validation, numeric validation with min/max/step, pattern matching, and field equality validation.
Hooks 2
hook_clientside_validation_validator_info_alter
Allows modules to alter the CvValidator plugin definitions. Can be used to add custom JavaScript libraries, modify supported element types, or change plugin behavior.
hook_clientside_validation_should_validate
Allows modules to control whether a specific form element should receive client-side validation. Return FALSE to skip validation for an element.
Drush Commands 3
drush clientside_validation_jquery:library-status
Shows whether the jQuery Validation library is installed locally in the /libraries directory.
drush clientside_validation_jquery:library-download
Downloads and installs the jQuery Validation library to /libraries/jquery-validation. Automatically extracts and renames the downloaded archive.
drush clientside_validation_jquery:library-remove
Removes the locally installed jQuery Validation library from /libraries/jquery-validation.
Troubleshooting 6
Check if the library is loaded by inspecting the page source for jquery.validate.min.js. If using local library, run 'drush cvjls' to check installation status. If not installed, either enable CDN in settings or run 'drush cvjld' to download.
Ensure the CDN URL is accessible from your server. The module validates the URL by checking if jquery.validate.min.js is accessible at the specified path. Use the format: https://cdn.jsdelivr.net/npm/jquery-validation@1.21.0/dist/
Either set 'Validate all forms before AJAX submit' to 'Yes' in the settings, or add the CSS class 'cv-validate-before-ajax' to forms that should be validated before AJAX submission.
Ensure the ckeditor module is enabled. The integration library is automatically loaded when CKEditor is present. If still not working, check browser console for JavaScript errors.
Enable the Inline Form Errors module to get consistent styling between client-side and server-side validation error messages.
Ensure you're using the correct property name for custom errors. Each validator has its own error property: #required_error, #email_error, #url_error, #min_error, #max_error, #step_error, #maxlength_error, #pattern_error, #equal_to_error, #url_internal_external_error.