Foundation for Sites6.3.1 changelog
Component List

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. Note the use of the novalidate attribute to disable any browser validation that could conflict with Abide.

Watch this part in video

edit on codepen button 
<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>

Here's how you use this input field!

Enter a password please.

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

Choose Your Favorite, and this is required, so you have to pick one.
Choose Your Favorite - not required, you can leave this one blank.
Check these out

 

There are some errors in your form.

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>

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.

NameTypeDefault ValueDescription
$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.

ParameterTypeDefault ValueDescription
$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

NameTypeDescription
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.

NameDescription
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

NameTypeDescription
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.

NameTypeDescription
$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
  2. The .closest()
NameTypeDescription
$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
  2. The .closest()
NameTypeDescription
$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

NameTypeDescription
$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

NameTypeDescription
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

NameTypeDescription
$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

NameTypeDescription
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.

NameTypeDescription
$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.

NameTypeDescription
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.

NameTypeDescription
$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.