Foundation
Jump to Nav

# Abide

JavaScript

Abide is a form validation library that extends the HTML5 validation API with custom validators.

## Abide Demo

These input types create a text field: `text`, `date`, `datetime`, `datetime-local`, `email`, `month`, `number`, `password`, `search`, `tel`, `time`, `url`, and `week`.

    <form data-abide novalidate>
      <div data-abide-error class="alert callout" style="display: none;">
        <p><i class="fi-alert"></i> There are some errors in your form.</p>
      </div>
      <div class="row">
        <div class="small-12 columns">
          <label>Number Required
            <input type="text" placeholder="1234" aria-describedby="exampleHelpText" required pattern="number">
            <span class="form-error">
              Yo, you had better fill this out, it's required.
            </span>
          </label>
          <p class="help-text" id="exampleHelpText">Here's how you use this input field!</p>
        </div>
        <div class="small-12 columns">
          <label>Password Required
            <input type="password" id="password" placeholder="yeti4preZ" aria-describedby="exampleHelpText" required >
            <span class="form-error">
              I'm required!
            </span>
          </label>
          <p class="help-text" id="exampleHelpText">Enter a password please.</p>
        </div>
        <div class="small-12 columns">
          <label>Re-enter Password
            <input type="password" placeholder="yeti4preZ" aria-describedby="exampleHelpText2" required pattern="alpha_numeric" data-equalto="password">
            <span class="form-error">
              Hey, passwords are supposed to match!
            </span>
          </label>
          <p class="help-text" id="exampleHelpText2">This field is using the `data-equalto="password"` attribute, causing it to match the password field above.</p>
        </div>
      </div>
      <div class="row">
        <div class="medium-6 columns">
          <label>URL Pattern, not required, but throws error if it doesn't match the Regular Expression for a valid URL.
            <input type="text" placeholder="http://foundation.zurb.com" pattern="url">
          </label>
        </div>
        <div class="medium-6 columns">
          <label>European Cars, Choose One, it can't be the blank option.
            <select id="select" required>
              <option value=""></option>
              <option value="volvo">Volvo</option>
              <option value="saab">Saab</option>
              <option value="mercedes">Mercedes</option>
              <option value="audi">Audi</option>
            </select>
          </label>
        </div>
      </div>
      <div class="row">
        <fieldset class="large-6 columns">
          <legend>Choose Your Favorite, and this is required, so you have to pick one.</legend>
          <input type="radio" name="pokemon" value="Red" id="pokemonRed"><label for="pokemonRed">Red</label>
          <input type="radio" name="pokemon" value="Blue" id="pokemonBlue" required><label for="pokemonBlue">Blue</label>
          <input type="radio" name="pokemon" value="Yellow" id="pokemonYellow"><label for="pokemonYellow">Yellow</label>
        </fieldset>
        <fieldset class="large-6 columns">
          <legend>Choose Your Favorite - not required, you can leave this one blank.</legend>
          <input type="radio" name="pockets" value="Red" id="pocketsRed"><label for="pocketsRed">Red</label>
          <input type="radio" name="pockets" value="Blue" id="pocketsBlue"><label for="pocketsBlue">Blue</label>
          <input type="radio" name="pockets" value="Yellow" id="pocketsYellow"><label for="pocketsYellow">Yellow</label>
        </fieldset>
        <fieldset class="large-6 columns">
          <legend>Check these out</legend>
          <input id="checkbox1" type="checkbox"><label for="checkbox1">Checkbox 1</label>
          <input id="checkbox2" type="checkbox" required><label for="checkbox2">Checkbox 2</label>
          <input id="checkbox3" type="checkbox"><label for="checkbox3">Checkbox 3</label>
        </fieldset>
      </div>
      <div class="row">
        <fieldset class="large-6 columns">
          <button class="button" type="submit" value="Submit">Submit</button>
        </fieldset>
        <fieldset class="large-6 columns">
          <button class="button" type="reset" value="Reset">Reset</button>
        </fieldset>
      </div>
    </form>

There are some errors in your form.

Number Required Yo, you had better fill this out, it's required.

Here's how you use this input field!

Password Required I'm required!

Enter a password please.

Re-enter Password Hey, passwords are supposed to match!

This field is using the `data-equalto="password"` attribute, causing it to match the password field above.

URL Pattern, not required, but throws error if it doesn't match the Regular Expression for a valid URL.
European Cars, Choose One, it can't be the blank option.
Choose Your Favorite, and this is required, so you have to pick one. Red Blue Yellow
Choose Your Favorite - not required, you can leave this one blank. Red Blue Yellow
Check these out Checkbox 1 Checkbox 2 Checkbox 3

There are some errors in your form.

Required Thing Yo, you had better fill this out. Required Thing

### Form Errors

Abide automatically detects Form Errors of an input by their class (`.form-error` by default, see the `formErrorSelector` option) when they are siblings of the input or inside the same parent.

When the Form Errors cannot be placed next to its field, like in an Input Group, the relation can be declared with `[data-form-error-for]` attribute.

    <form data-abide novalidate>
      <label>
        Amount
        <div class="input-group">
          <span class="input-group-label">$</span>
          <input class="input-group-field" id="exampleNumberInput" type="number" required pattern="number"/>
        </div>
        <span class="form-error" data-form-error-for="exampleNumberInput">Amount is required.</span>
      </label>
      <button class="button" type="submit" value="Submit">Submit</button>
    </form>

Amount
$
Amount is required.

## Initial State

    <form data-abide>
      <!-- Add "display: none" right away -->
      <div data-abide-error class="alert callout" style="display: none;">
        <p><i class="fi-alert"></i> There are some errors in your form.</p>
      </div>
      <label>
        Name
        <input type="text" required>
        <span class="form-error">This field is required.</span>
      </label>
    </form>

## Error State

    <form data-abide>
      <!-- Add role="alert" -->
      <!-- Add "display: block" -->
      <div data-abide-error role="alert" class="alert callout" style="display: block;">
        <p><i class="fi-alert"></i> There are some errors in your form.</p>
      </div>
      <!-- Add "is-invalid-label" -->
      <label class="is-invalid-label">
        Name
        <!-- Add "is-invalid-input" -->
        <input type="text" class="is-invalid-input" required aria-invalid aria-describedby="uuid">
        <!-- Add "is-visible" -->
        <span class="form-error is-visible" id="uuid">This field is required.</span>
      </label>
    </form>

## Ignored Inputs

    <form data-abide>
        <div class="small-12 columns">
          <label>Nothing Required!
            <input type="text" placeholder="Use me, or don't" aria-describedby="exampleHelpTex" data-abide-ignore>
          </label>
          <p class="help-text" id="exampleHelpTex">This input is ignored by Abide using `data-abide-ignore`</p>
        </div>
        <div class="small-12 columns">
          <label>Disabled!
            <input type="text" placeholder="Disabled input" aria-describedby="exampleHelpTex" disabled>
          </label>
          <p class="help-text" id="exampleHelpTex">This input is ignored by Abide using `disabled`</p>
        </div>
        <div class="small-12 columns">
          <label>Hidden!
            <input type="hidden" placeholder="Hidden input" aria-describedby="exampleHelpTex" >
          </label>
          <p class="help-text" id="exampleHelpTex">This input is ignored by Abide using `type="hidden"`</p>
        </div>
      <div class="row">
        <fieldset class="large-6 columns">
          <button class="button" type="submit" value="Submit">Submit</button>
        </fieldset>
        <fieldset class="large-6 columns">
          <button class="button" type="reset" value="Reset">Reset</button>
        </fieldset>
      </div>
    </form>

## Event Listener

Setup event listener after foundation is initialized (especially for formvalid/forminvalid). Easier to chain via document selector.

- valid.zf.abide and invalid.zf.abide are field level events, triggered in validateInput function
  - ev.target is the DOM field element,
  - elem is jQuery selector for field element
- formvalid.zf.abide and forminvalid.zf.abide are form events, triggered in validateForm function
  - ev.target is the DOM form element,
  - frm is jQuery selector for form element

    $(document)
      // field element is invalid
      .on("invalid.zf.abide", function(ev,elem) {
        console.log("Field id "+ev.target.id+" is invalid");
      })
      // field element is valid
      .on("valid.zf.abide", function(ev,elem) {
        console.log("Field name "+elem.attr('name')+" is valid");
      })
      // form validation failed
      .on("forminvalid.zf.abide", function(ev,frm) {
        console.log("Form id "+ev.target.id+" is invalid");
      })
      // form validation passed, form will submit if submit event not returned false
      .on("formvalid.zf.abide", function(ev,frm) {
        console.log("Form id "+frm.attr('id')+" is valid");
        // ajax post form
      })
      // to prevent form from submitting upon successful validation
      .on("submit", function(ev) {
        ev.preventDefault();
        console.log("Submit for form id "+ev.target.id+" intercepted");
      });
    // You can bind field or form event selectively
    $("#foo").on("invalid.zf.abide", function(ev,el) {
      alert("Input field foo is invalid");
    });
    $("#bar").on("formvalid.zf.abide", function(ev,frm) {
      alert("Form is valid, finally!");
      // do something perhaps
    });

## Builtin Patterns and Validators

The following patterns and validators are already built in:

`alpha`, `alpha_numeric`, `card`, `color` `cvv`, `date`, `dateISO`, `datetime`, `day_month_year`, `domain`, `email`, `integer`, `month_day_year`, `number`, `time`, `url`

They are defined by regular expressions as you can see below. Note, that the patterns that relate to text such as `alpha` and `alpha_numeric` do not consider special characters from other languages. You need to add these special characters yourself to the regular expressions. For instance, for the German language you need to add:

    alpha : /^[a-zäöüßA-ZÄÖÜ]+$/,
    alpha_numeric : /^[a-zäöüßA-ZÄÖÜ0-9]+$/,

Then you need to customize the builtin patterns as explained in the next section. Otherwise Abide will produce an error if a special character is input in your text field which is validated with `pattern="alpha"` or `pattern="alpha_numeric"`.

Here are the definitions of the builtin patterns:

    alpha : /^[a-zA-Z]+$/,
    alpha_numeric : /^[a-zA-Z0-9]+$/,
    integer : /^[-+]?\d+$/,
    number : /^[-+]?\d*(?:[\.\,]\d+)?$/,

    // amex, visa, diners
    card : /^(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|6(?:011|5[0-9][0-9])[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|(?:2131|1800|35\d{3})\d{11})$/,
    cvv : /^([0-9]){3,4}$/,

    // http://www.whatwg.org/specs/web-apps/current-work/multipage/states-of-the-type-attribute.html#valid-e-mail-address
    email : /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+$/,

    url : /^(https?|ftp|file|ssh):\/\/(((([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:)*@)?(((\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5])\.(\d|[1-9]\d|1\d\d|2[0-4]\d|25[0-5]))|((([a-zA-Z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-zA-Z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-zA-Z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-zA-Z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-zA-Z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-zA-Z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?)(:\d*)?)(\/((([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)+(\/(([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)*)*)?)?(\?((([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|[\uE000-\uF8FF]|\/|\?)*)?(\#((([a-zA-Z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(%[\da-f]{2})|[!\$&'\(\)\*\+,;=]|:|@)|\/|\?)*)?$/,
    // abc.de
    domain : /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,8}$/,

    datetime : /^([0-2][0-9]{3})\-([0-1][0-9])\-([0-3][0-9])T([0-5][0-9])\:([0-5][0-9])\:([0-5][0-9])(Z|([\-\+]([0-1][0-9])\:00))$/,
    // YYYY-MM-DD
    date : /(?:19|20)[0-9]{2}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1[0-9]|2[0-9])|(?:(?!02)(?:0[1-9]|1[0-2])-(?:30))|(?:(?:0[13578]|1[02])-31))$/,
    // HH:MM:SS
    time : /^(0[0-9]|1[0-9]|2[0-3])(:[0-5][0-9]){2}$/,
    dateISO : /^\d{4}[\/\-]\d{1,2}[\/\-]\d{1,2}$/,
    // MM/DD/YYYY
    month_day_year : /^(0[1-9]|1[012])[- \/.](0[1-9]|[12][0-9]|3[01])[- \/.]\d{4}$/,
    // DD/MM/YYYY
    day_month_year : /^(0[1-9]|[12][0-9]|3[01])[- \/.](0[1-9]|1[012])[- \/.]\d{4}$/,

    // #FFF or #FFFFFF
    color : /^#?([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$/

## Adding Custom Pattern and Validator

- Override builtin patterns and validators before foundation is initialized
- Add new patterns and validators before or after foundation is initialized

    $(document).foundation();
    Foundation.Abide.defaults.patterns['dashes_only'] = /^[0-9-]*$/;
    Foundation.Abide.defaults.validators['greater_than'] =
    function($el,required,parent) {
      // parameter 1 is jQuery selector
      if (!required) return true;
      var from = $('#'+$el.attr('data-greater-than')).val(),
          to = $el.val();
      return (parseInt(to) > parseInt(from));
    };

    <input id="phone" type="text" pattern="dashes_only" required >
    <input id="min" type="number" required >
    <input id="max" type="number" data-validator="greater_than" data-greater-than="min" required>

## Sass Reference

### Variables

The default styles of this component can be customized using these Sass variables in your project's settings file.

Name | Type | Default Value | Description
--- | --- | --- | ---
`$abide-inputs` | Boolean | `true` | Sets if error styles should be added to inputs.
`$abide-labels` | Boolean | `true` | Sets if error styles should be added to labels.
`$input-background-invalid` | Color | `get-color(alert)` | Background color to use for invalid text inputs.
`$form-label-color-invalid` | Color | `get-color(alert)` | Color to use for labels of invalid inputs.
`$input-error-color` | Color | `get-color(alert)` | Default font color for form error text.
`$input-error-font-size` | Number | `rem-calc(12)` | Default font size for form error text.
`$input-error-font-weight` | Keyword | `$global-weight-bold` | Default font weight for form error text.

### Mixins

We use these mixins to build the final CSS output of this component. You can use the mixins yourself to build your own class structure out of our components.

#### form-input-error

    @include form-input-error($background, $background-lighten);

Styles the background and border of an input field to have an error state.

Parameter | Type | Default Value | Description
--- | --- | --- | ---
`$background` | Color | `$alert-color` | Color to use for the background and border.
`$background-lighten` | Number | `10%` | Lightness level of the background color.

#### form-error

    @include form-error;

Adds error styles to a form element, using the values in the settings file.

## JavaScript Reference

### Initializing

The file `foundation.abide.js` must be included in your JavaScript to use this plugin, along with `foundation.core.js`.

### Foundation.Abide

Creates a new instance of Abide.

    var elem = new Foundation.Abide(element, options);

Fires these events: Abide#event:init

Name | Type | Description
--- | --- | ---
`element` | Object | jQuery object to add the trigger to.
`options` | Object | Overrides to the default plugin settings.

### Plugin Options

Use these options to customize an instance of Abide. Plugin options can be set as individual data attributes, one combined `data-options` attribute, or as an object passed to the plugin's constructor. Learn more about how JavaScript plugins are initialized.

Name | Type | Default | Description
--- | --- | --- | ---
`data-validate-on` | `string` | `fieldChange` | The default event to validate inputs. Checkboxes and radios validate immediately. Remove or change this value for manual validation.
`data-label-error-class` | `string` | `is-invalid-label` | Class to be applied to input labels on failed validation.
`data-input-error-class` | `string` | `is-invalid-input` | Class to be applied to inputs on failed validation.
`data-form-error-selector` | `string` | `.form-error` | Class selector to use to target Form Errors for show/hide.
`data-form-error-class` | `string` | `is-visible` | Class added to Form Errors on failed validation.
`data-live-validate` | `boolean` | `false` | Set to true to validate text inputs on any value change.
`data-validate-on-blur` | `boolean` | `false` | Set to true to validate inputs on blur.
`data-validators` | `` | `` | Optional validation functions to be used. `equalTo` being the only default included function. Functions should return only a boolean if the input is valid or not. Functions are given the following arguments: el : The jQuery element to validate. required : Boolean value of the required attribute be present or not. parent : The direct parent of the input.

### Events

These events will fire from any element with a Abide plugin attached.

Name | Description
--- | ---
`invalid.zf.abide` | Fires when the input is done checking for validation. Event trigger is either `valid.zf.abide` or `invalid.zf.abide` Trigger includes the DOM element of the input.
`forminvalid.zf.abide` | Fires when the form is finished validating. Event trigger is either `formvalid.zf.abide` or `forminvalid.zf.abide`. Trigger includes the element of the form.
`formreset.zf.abide` | Fires when the form has been reset.

### Methods

#### requiredCheck

    $('#element').foundation('requiredCheck', element);

Checks whether or not a form element has the required attribute and if it's checked or not

Name | Type | Description
--- | --- | ---
`element` | Object | jQuery object to check for required attribute

#### findFormError

    $('#element').foundation('findFormError', $el);

Get:

- Based on $el, the first element(s) corresponding to `formErrorSelector` in this order:
  1. The element's direct sibling('s).
  2. The element's parent's children.
- Element(s) with the attribute `[data-form-error-for]` set with the element's id.

This allows for multiple form errors per input, though if none are found, no form errors will be shown.

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to use as reference to find the form error selector.

#### findLabel

    $('#element').foundation('findLabel', $el);

Get the first element in this order:

1. The with the attribute `[for="someInputId"]`
2. The `.closest()`

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to check for required attribute

#### findRadioLabels

    $('#element').foundation('findRadioLabels', $el);

Get the set of labels associated with a set of radio els in this order

1. The with the attribute `[for="someInputId"]`
2. The `.closest()`

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to check for required attribute

#### addErrorClasses

    $('#element').foundation('addErrorClasses', $el);

Adds the CSS error class as specified by the Abide settings to the label, input, and the form

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to add the class to

#### removeRadioErrorClasses

    $('#element').foundation('removeRadioErrorClasses', groupName);

Remove CSS error classes etc from an entire radio button group

Name | Type | Description
--- | --- | ---
`groupName` | String | A string that specifies the name of a radio button group

#### removeErrorClasses

    $('#element').foundation('removeErrorClasses', $el);

Removes CSS error class as specified by the Abide settings from the label, input, and the form

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to remove the class from

#### validateInput

    $('#element').foundation('validateInput', element);

Goes through a form to find inputs and proceeds to validate them in ways specific to their type. Ignores inputs with data-abide-ignore, type="hidden" or disabled attributes set

Fires these events: Abide#event:invalid Abide#event:valid

Name | Type | Description
--- | --- | ---
`element` | Object | jQuery object to validate, should be an HTML input

#### validateForm

    $('#element').foundation('validateForm');

Goes through a form and if there are any invalid inputs, it will display the form error element

Fires these events: Abide#event:formvalid Abide#event:forminvalid

#### validateText

    $('#element').foundation('validateText', $el, pattern);

Determines whether or a not a text input is valid based on the pattern specified in the attribute. If no matching pattern is found, returns true.

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery object to validate, should be a text input HTML element
`pattern` | String | string value of one of the RegEx patterns in Abide.options.patterns

#### validateRadio

    $('#element').foundation('validateRadio', groupName);

Determines whether or a not a radio input is valid based on whether or not it is required and selected. Although the function targets a single `<input>`, it validates by checking the `required` and `checked` properties of all radio buttons in its group.

Name | Type | Description
--- | --- | ---
`groupName` | String | A string that specifies the name of a radio button group

#### matchValidation

    $('#element').foundation('matchValidation', $el, validators, required);

Determines if a selected input passes a custom validation function. Multiple validations can be used, if passed to the element with `data-validator="foo bar baz"` in a space separated listed.

Name | Type | Description
--- | --- | ---
`$el` | Object | jQuery input element.
`validators` | String | a string of function names matching functions in the Abide.options.validators object.
`required` | Boolean | self explanatory?

#### resetForm

    $('#element').foundation('resetForm');

Resets form inputs and styles

Fires these events: Abide#event:formreset

#### destroy

    $('#element').foundation('destroy');

Destroys an instance of Abide. Removes error styles and classes from elements, without resetting their values.