Skip to content

Latest commit

 

History

History
executable file
·
307 lines (211 loc) · 11.3 KB

README.md

File metadata and controls

executable file
·
307 lines (211 loc) · 11.3 KB
Raw

Validate.js

A lightweight form validation script that augments native HTML5 form validation elements and attributes, providing a better user experience and giving you more control.

When a visitor leaves a field, Validate.js immediately validates the field and displays an error if applicable. It also validates the entire form on submit, and provides support for custom onSubmit() functions (for example, Ajax form submission). You can pass an option to activate live validation on fields while the visitor is still typing. It allows for custom errors.

Regarding the original script by Chris Ferdinandi: Download Validate / View the demo

Download this fork of Validate

This fork builds on v1.1.3 and adds the following features:

  • optional live validation while the visitor is still typing (v1.2.0) — see below for how to pass options
  • delay live validation for invalid values while still typing, but immediately show positive feedback for valid values ("reward early, punish late") (v1.4.0)
  • integration for custom errors by providing a wrapper around the HTML5 Constraint API setCustomValidity() function (v.1.3.0) — see below for an example to use the setCustomError() method

Want to learn how to write your own vanilla JS plugins? Get Chris Ferdinandi's free daily developer tips and level-up as a web developer. 🚀

Getting Started

Compiled and production-ready code can be found in the dist directory. The src directory contains development code.

1. Include Validate.js on your site.

<script src="dist/js/validate.js"></script>

2. Use HTML5 semantic input types and validation-related attributes on your form fields.

Add the required attribute to required fields. Use type="email" and type="url" for email addresses and URLs, respectively. Include pattern attributes, min and max, and so on to set validation criteria for your form fields. View a full list of types and attributes on MDN.

<div>
	<label for="email">Email</label>
	<input type="email" id="email" required>
</div>

<div>
	<label for="url">URL</label>
	<input type="url" id="url" required>
</div>

If you're using validation patterns, you can also include a title with a custom validation message. This will display in the error message.

<div>
	<label for="password">Password (At least 1 uppercase character, 1 lowercase character, and 1 number)</label>
	<input type="password" id="password" value="" title="Please choose a password that includes at least 1 uppercase character, 1 lowercase character, and 1 number." pattern="^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?!.*\s).*$" required>
</div>

3. Flag your form for validation.

Add the [data-validate] attribute to any forms you want validated.

<form data-validate>
	...
</form>

4. Initialize Validate.js.

In the footer of your page, after the content, initialize Validate.js. And that's it, you're done. Nice work!

<script>
	validate.init();
</script>

Styling Errors

Validate.js does not come pre-packaged with any styles for fields with errors or error messages. Use the .error class to style fields, and the .error-message class to style error messages.

Need a starting point? Here's some really lightweight CSS you can use.

/**
 * Form Validation Errors
 */
.error {
	border-color: red;
}

.error-message {
	color: red;
	font-style: italic;
	margin-bottom: 1em;
}

Installing with Package Managers

You can install Validate.js with your favorite package manager directly from GitHub (it's not available on NPM).

  • NPM: npm install cferdinandi/validate
  • Bower: bower install https://github.com/cferdinandi/validate.git

Working with the Source Files

If you would prefer, you can work with the development code in the src directory using the included Gulp build system. This compiles, lints, and minifies code.

Dependencies

Make sure these are installed first.

Quick Start

  1. In bash/terminal/command line, cd into your project directory.
  2. Run npm install to install required files.
  3. When it's done installing, run one of the task runners to get going:
    • gulp manually compiles files.
    • gulp watch automatically compiles files when changes are made and applies changes using LiveReload.

Options and Settings

Validate.js includes smart defaults and works right out of the box. But if you want to customize things, it also has a robust API that provides multiple ways for you to adjust the default options and settings.

Global Settings

You can pass options and callbacks into Validate through the init() function:

validate.init({

	// Classes and Selectors
	selector: '[data-validate]', // The selector for forms to validate
	fieldClass: 'error', // The class to apply to fields with errors
	errorClass: 'error-message', // The class to apply to error messages

	// Messages
	messageValueMissing: 'Please fill out this field.', // Displayed when a required field is left empty
	messageTypeMismatchEmail: 'Please enter an email address.', // Displayed when a `type="email"` field isn't a valid email
	messageTypeMismatchURL: 'Please enter a URL.', // Displayed when a `type="url"` field isn't a valid URL
	messageTooShort: 'Please lengthen this text to {minLength} characters or more. You are currently using {length} characters.', // Displayed with the `minLength` attribute is used and the input value is too short
	messageTooLong: 'Please shorten this text to no more than {maxLength} characters. You are currently using {length} characters.', // Displayed with the `maxLength` attribute is used and the input value is too long
	messagePatternMismatch: 'Please match the requested format.', // Displayed with the `pattern` attribute is used and the pattern doesn't match (if a `title` attribute is used, that's displayed instead)
	messageBadInput: 'Please enter a number.', // Displayed when the field is numeric (ex. `type="number"`) but the value is not a number
	messageStepMismatch: 'Please select a valid value.', // Displayed when the `step` attribute is used and the value doesn't adhere to it
	messageRangeOverflow: 'Please select a value that is no more than {max}.', // Displayed with the `max` attribute is used and the input value is too hight
	messageRangeUnderflow: 'Please select a value that is no less than {min}.', // Displayed with the `mind` attribute is used and the input value is too low
	messageGeneric: 'The value you entered for this field is invalid.', // A catchall error, displayed when the field fails validation and none of the other conditions apply

	// Live Validation
	useLiveValidation: false, // Update errors instantly while the visitor is typing
	rewardEarlyPunishLate: true, // Delay feedback for invalid values, update errors instantly for valid values only
	punishLateTimeout: 1000, // Milliseconds to delay live validation feedback for invalid values 

	// Form Submission
	disableSubmit: false, // If true, don't submit the form to the server (for Ajax for submission)
	onSubmit: function (form, fields) {}, // Function to run if the form successfully validates

	// Callbacks
	beforeShowError: function (field, error) {}, // Function to run before an error is display
	afterShowError: function (field, error) {}, // Function to run after an error is display
	beforeRemoveError: function (field) {}, // Function to run before an error is removed
	afterRemoveError: function (field) {}, // Function to run after an error is removed

});

Use Validate.js events in your own scripts

You can also call Validate.js's public methods in your own scripts.

hasError()

Check if a field has a validation error.

validate.hasError(
	field, // The field to validate
	options // User settings, same as the ones passed in during validate.init() [optional]
);

Example

var field = document.querySelector('[name="email"]');
var error = validate.hasError(field);

if (error) {
	// Do something...
}

showError()

Show an error message on a field.

validate.showError(
	field, // The field to show an error message for
	error, // The error message to show
	options // User settings, same as the ones passed in during validate.init() [optional]
);

Example 1: Write your own error

var field = document.querySelector('[name="email"]');
var error = 'This field is wrong, dude!';
validate.showError(field, error);

Example 2: Using hasError()

var field = document.querySelector('[name="url"]');
var error = validate.hasError(field);
validate.showError(field, error);

removeError()

Remove the error message from a field.

/**
 * Remove an error message from a field
 * @public
 * @param  {Node}   field   The field to remove the error from
 * @param  {Object} options User options
 */
validate.removeError(
	field, // The field to remove the error from
	options // User settings, same as the ones passed in during validate.init() [optional]
);

Example

var field = document.querySelector('[name="email"]');
validate.removeError(field);

setCustomError()

Set or remove a custom error. This wraps around the HTML5 Constraint API setCustomValidity() function.

/**
 * Set or remove a custom error
 * @public
 * @param  {Node}   field   	 The field to set the custom error on
 * @param  {String} errorMessage Custom error message or empty string to remove a custom error
 */
validate.setCustomError(
	field, // The field to set the custom error on
	errorMessage // Custom error message or empty string to remove a custom error
);

Example

var field = document.querySelector('[name="email"]');
validate.setCustomError(field, 'This email address is already registered')

destroy()

Destroy the current validate.init(). Removes all errors and resets the DOM. This is called automatically during the init function to remove any existing initializations.

validate.destroy();

Browser Compatibility

Validate.js works in all modern browsers, and (mostly) IE 10 and above.

Unfortunately, not all validation types are supported by all versions of IE and Edge consistently. For example, IE10 and IE11 will check if a form input is too long (using the maxLength attribute), but Edge will not. And no version of IE or Edge will check if it's too short (using the minLength attribute).

A Polyfill

Validate.js includes an optional polyfill (validityState-polyfill.js) that you can include to push support back to IE10, and add missing features to partially supported browsers.

If you also include Eli Grey's classList.js polyfill, you can push support even further, back to IE9.

How to Contribute

Please review the contributing guidelines.

License

The code is available under the MIT License.