Bouncer.js

A lightweight form validation script that augments native HTML5 form validation elements and attributes.

Features:

Fields validate on blur (as the user moves out of them), which data shows is the best time for cognitive load.
The entire form is validated on submit.
Fields with errors are revalidated as the user types. Errors are removed the instant the field is valid.
Supports custom validation patterns and error messages.

<hr>

Want to learn how to write your own vanilla JS plugins? Check out my Vanilla JS Pocket Guides or join the Vanilla JS Academy and level-up as a web developer. 🚀

<hr>

Getting Started

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

1. Include Bouncer on your site.

There are two versions of Bouncer: the standalone version, and one that comes preloaded with polyfills for closest(), matches(), classList, and CustomEvent(), which are only supported in newer browsers.

If you're including your own polyfills or don't want to enable this feature for older browsers, use the standalone version. Otherwise, use the version with polyfills.

Direct Download

You can download the files directly from GitHub.

<script src="path/to/bouncer.polyfills.min.js"></script>

CDN

You can also use the jsDelivr CDN. I recommend linking to a specific version number or version range to prevent major updates from breaking your site. Smooth Scroll uses semantic versioning.

<!-- Always get the latest version -->
<!-- Not recommended for production sites! -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/bouncer/dist/bouncer.polyfills.min.js"></script>

<!-- Get minor updates and patch fixes within a major version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/bouncer@1/dist/bouncer.polyfills.min.js"></script>

<!-- Get patch fixes within a minor version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/bouncer@1.0/dist/bouncer.polyfills.min.js"></script>

<!-- Get a specific version -->
<script src="https://cdn.jsdelivr.net/gh/cferdinandi/bouncer@1.0.0/dist/bouncer.polyfills.min.js"></script>

NPM

You can also use NPM (or your favorite package manager).

npm install formbouncerjs

2. Add browser-native form validation attributes to your markup.

No special markup needed—just browser-native validation attributes (like required) and input types (like email or number).

<form>
	<label for="email">Your email address</label>
	<input type="email" name="email" id="email">
	<button>Submit</button>
</form>

3. Initialize Bouncer.

In the footer of your page, after the content, initialize Bouncer by passing in a selector for the forms that should be validated.

If the form has errors, submission will get blocked until they're corrected. Otherwise, it will submit as normal.

And that's it, you're done. Nice work!

<script>
	var validate = new Bouncer('form');
</script>

Form Validation Attributes

Modern browsers provide built-in form validation.

Bouncer hooks into those native attributes, suppressing the native validation and running its own. If Bouncer fails to load or run, the browser-native validation will run in its place.

Required fields

Add the required attribute to any field that must be filled out or selected.

<input type="text" name="first-name" required>

Special Input Types

You can use special type attribute values to indicate specific types of data that should be captured.

<!-- Must be a valid email address -->
<input type="email" name="email">

<!-- Must be a valid URL -->
<input type="url" name="website">

<!-- Must be a number -->
<input type="number" name="age">

<!-- Must be a date in YYYY-MM-DD format (many browsers include a native date picker for this) -->
<input type="date" name="dob">

<!-- Must be a time in 24-hour format (many browsers include a native date picker for this) -->
<input type="time" name="time">

<!-- Must be a month/year in YYYY-MM format (many browsers include a native date picker for this) -->
<input type="month" name="birthday">

<!-- Must be a color in #rrggbb format (many browsers include a native color picker for this) -->
<input type="color" name="color">

Min and Max Values

For numbers that should not go below or exceed a certain value, you can use the min and max attributes, respectively.

<!-- Cannot exceed 72 -->
<input type="number" max="72" name="answer">

<!-- Cannot be below 37 -->
<input type="number" min="37" name="answer">

<!-- They can also be combined -->
<input type="number" min="37" max="72" name="answer">

Min and Max Length

For inputs that should not be shorter or longer than a certain number of characters, you can use the minlength and maxlength attributes, respectively.

<!-- Cannot be shorter than 12 characters -->
<input type="password" minlength="12" name="password">

<!-- Cannot be longer than 24 characters -->
<input type="text" maxlength="24" name="first-name">

<!-- They can also be combined -->
<input type="text" minlength="7" maxlength="24" name="favorite-pixar-character">

Custom Validation Patterns

You can use your own validation pattern for a field with the pattern attribute. This uses regular expressions.

<!-- Phone number be in 555-555-5555 format -->
<input type="text" name="tel" pattern="\d{3}[\-]\d{3}[\-]\d{4}">

Custom Pattern Mismatch Error Messages

Show custom errors for pattern mismatches by adding the [data-bouncer-message] attribute to the field.

<!-- Phone number be in 555-555-5555 format -->
<input type="text" name="tel" pattern="\d{3}[\-]\d{3}[\-]\d{4}" data-bouncer-message="Please use the following format: 555-555-5555">

Error Styling

Bouncer 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;
}

Error Types

Bouncer captures four different types of field errors:

missingValue errors occur when a required field has no value (or for checkboxes and radio buttons, nothing is selected).
patternMismatch errors occur when a value doesn't match the expected pattern for a particular input type, or a pattern provided by the pattern attribute.
outOfRange errors occur when a number is above or below the min or max values.
wrongLength errors occur when the input is longer or shorter than the minlength and maxlength values.

The patterns and messages associated with these types of errors can be customized.

Custom Validation Types

You can add custom validation types to Bouncer beyond the four standard validations.

You can see this feature in action with the Confirm Password field on the demo page, and view examples of custom validations in the Cookbook (coming soon).

Adding custom validations

Pass in a customValidations object as an option when instantiating a new Bouncer instance. Each property in the object is a new validation type. Each value should be a function that accepts two arguments: the field being validated and the settings for the current instantiation.

The function should check if the field has an error. Return true if there's an error, and false when there's not.

var validate = new Bouncer('form', {
	customValidations: {
		isHello: function (field) {

			// Return false because there is NO error
			if (field.value === 'hello') return false;

			// Return true when there is
			return true;

		}
	}
});

Creating custom validation error messages

Add an error message for the custom validation by including the messages object in your options.

The key should be the same as your custom validation. It's value can be a string, or a function that returns a string. Message functions can accept two arguments: the field being validated and the settings for the current instantiation.

var validate = new Bouncer('form', {
	customValidations: {
		isHello: function (field) {

			// Return false because there is NO error
			if (field.value === 'hello') return false;

			// Return true when there is
			return true;

		}
	},
	messages: {
		// As a string
		isHello: 'This field should have a value of "hello"',

		// As a function
		isHello: function () {
			return 'This field should have a value of "hello"';
		}
	}
});

Error Message Location

By default, bouncer will render error messages after the invalid field (or the label for it, if the field is a radio or checkbox).

You can optionally render error messages before the field by setting the messageAfterField option to false.

var validate = new Bouncer('form', {
	messageAfterField: false
});

You can also assign a custom location for an error message by including the [data-bouncer-target] attribute on a field. Use a

Bouncer

Install / Use

README