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. 1.5)

Note

This page is archived under version 1.5 and is available for reference purposes only. The latest version of Pattern Library is 2.

Form validation

Validation plugin

Pattern Library uses the open source jQuery Validation Plugin for client-side form validation. The plugin is written and maintained by Jörn Zaefferer, a member of the jQuery team and lead developer on the jQuery UI team. The plugin is also used by Web Experience Toolkit, an open source project led by the Government of Canada.

Load the coc.forms.js file for Pattern Library’s UX enhancements to the jQuery Validation Plugin. 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-2.2.4.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
        // generate enhanced form controls (generates individual 'clear' and 'show password'
        // button controls for supported .form-control elements)
        COCPL_Form.init();
        // OR use the following line to initialize the validation ONLY
        COCPL_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 for validation AND enhanced form controls -->
<form class="form-width-md" data-pl-frm-vld="true" data-pl-frm-ctrl="true">
    ...
</form>

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

Specialized validation

Add specialized validation to an input field by applying the following attributes to the input tag.

Attribute Validation type
type="email" Email
data-rule-equalTo="#x" Equal to field with id="x"
This attribute is particularly useful for confirming passwords upon account creation.
minlength="x" Minimum number of characters for the input
maxlength="x" Maximum number of characters for the input


Unable to use these plugins?

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 for reference for how the validation feedback is structured and styled.

Example invalid state

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

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="#example-error-email"><span class="prefix">Error&nbsp;1: </span>Email address - Please enter a valid email address.</a></li>
        </ul>
    </section>

    <div class="form-group">
        <label for="example-error-email">
            <span class="field-name">Email address</span>
            <span class="label-required">(required)</span>
        </label>
        <input id="example-error-email" name="example-error-email" type="email" class="form-control error" value="john doe calgary.ca">
        <label for="example-error-email" class="error">
            <span class="prefix">Error&nbsp;1: </span>Please enter a valid email address.
        </label>
    </div>
</form>

Example success state

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="example-success-email">
            <span class="field-name">Email address</span>
            <span class="label-required">(required)</span>
        </label>
        <input id="example-success-email" name="example-success-email" type="email" class="form-control success" value="john.doe@calgary.ca">
        <label for="example-success-email" class="success">Valid</label>
    </div>
</form>