Information This site is moving

The Pattern Library is moving to its new home on the Summit design system site.

Go to the Summit site
Pattern Library (ver. 2)

Form validation

Pattern Library uses the open source jQuery Validation Plugin for client-side form validation. Additional UX enhancements are included in coc.forms.js. These enhancements are based off the Web Experience Toolkit’s validation UX and include a summary alert banner and styled inline alerts.

Demo

Try to submit the button below. JavaScript will relay feedback if any fields are incorrectly filled in.

Example optional helper text:
Your username is the email you used to sign up for this account.

Example optional helper text:
Your password contains at least 8 characters.

How to use

1. Load the 3 JavaScript files to your page and call one of the initialization lines:


<script src="js/jquery-3.5.1.min.js"></script>
<script src="js/jquery.validate.min.js"></script>
<script src="js/coc.forms.js"></script>
<script>
	$( document ).ready( function() {
		// Use the following line to initialize the validation AND to generate the enhanced form controls.
		COC.Form.init();

		// OR use the following line to initialize ONLY the validation.
		COC.Form.initValidation();
	});
</script>

2. Add this data attribute to any forms you wish to apply validation: data-pl-frm-vld="true".


<!-- Example form with the data-attributes to trigger the validation AND the enhanced form controls. -->
<form class="form-width-md" data-pl-frm-vld="true" data-pl-frm-ctrl="true">
	...
</form>

<!-- Example form with the data-attribute to trigger the validation ONLY. -->
<form class="form-width-md" data-pl-frm-vld="true">
	...
</form>

Supported validation rules

Below are some of the supported validation rules that can be applied to an input field.

Attribute Code example Description
required aria-required="true" <input type="text" class="form-control" required aria-required="true" ...> A value for the input is required.
type="email" <input type="email" class="form-control" ...> The input must be a properly formatted email address.
data-rule-equalTo="#x" <input id="password1" type="password" class="form-control" ...>
<input id="password2" type="password" class="form-control" data-rule-equalTo="#password1" ...>
The input must be exactly equal to the value of the input whose id equals "x".
This attribute is particularly useful for confirming passwords upon an account creation.
minlength="x" <input type="text" minlength="1" class="form-control" ...> Minimum number of characters for the input
maxlength="x" <input type="text" maxlength="255" class="form-control" ...> Maximum number of characters for the input
type="number" <input type="number" class="form-control" ...> The input must be a number.
type="number" min="x" <input type="number" min="0" class="form-control" ...> Minimum numerical value for the input.
type="number" max="x" <input type="number" max="999999" class="form-control" ...> Maximum numerical value for the input.
type="number" min="0" max="999999" <input type="number" min="0" max="999999" class="form-control" ...> Minimum and maximum numerical value for the input.

Unable to use the validation plugin?

If your project will be using its own form validation plugins or custom scripts, keep the following validation functionality in mind:

  • Display an inline-alert below the input field if there is an error.
  • Generate an alert banner at the top of the form to list out and link to each form error.
  • For accessibility, if the user submits the form with errors, the alert banner should receive focus. This allows the user to see all of the form errors from a high-level.
  • Once an error has been fixed, remove the corresponding error messages.

Validation state examples

The following may be used as reference for how the validation feedback is structured and styled.

Example invalid state

The form could not be submitted because 1 error was found.

Error 1: Please enter a valid email address.

Code


<form class="form-width-md">
	<section id="errors-validation-example" class="alert alert-danger" tabindex="-1">
		<h2>The form could not be submitted because 1 error was found.</h2>
		<ul>
			<li><a href="#{{ Input id }}"><span class="prefix">Error&nbsp;1: </span>{{ Label }} - {{ Validation message (e.g. Please enter a valid email address.) }}</a></li>
		</ul>
	</section>

	<div class="form-group">
		<label for="{{ Input id }}">{{ Label }} <span class="label-required">(required)</span></label>
		<input id="{{ Input id }}" name="{{ Input name }}" type="email" class="form-control error" value="{{ Value }}" aria-describedby="{{ Validation message id }}">
		<span id="{{ Validation message id }}" class="form-vld-msg error">
			<span class="prefix">Error&nbsp;1: </span>{{ Validation message (e.g. Please enter a valid email address.) }}
		</span>
	</div>
</form>

Example success state

Valid

In most cases, the success state does not need to be displayed. Example usage could include confirmation that:

  • an email address or username is unique to the database
  • a street address is valid

Note: The validation plugin does not relay success feedback. To showcase the success validation, custom adjustments to the JavaScript will be required.

Code


<form class="form-width-md">
	<div class="form-group">
		<label for="{{ Input id }}">{{ Label }} <span class="label-required">(required)</span></label>
		<input id="{{ Input id }}" name="{{ Input name }}" type="email" class="form-control valid" value="{{ Value }}" aria-describedby="{{ Validation message id }}">
		<span id="{{ Validation message id }}" class="form-vld-msg valid">{{ Validation message (e.g. Valid) }}</span>
	</div>
</form>