Abide
JavaScriptAbide is an 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>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>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.
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>
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
});
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 | map-get($foundation-palette, alert) |
Background color to use for invalid text inputs. |
$form-label-color-invalid |
Color | map-get($foundation-palette, alert) |
Color to use for labels of invalid inputs. |
$input-error-color |
Color | map-get($foundation-palette, 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-alpha);
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-alpha |
Number | 0.1 |
Transparency 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 following files must be included in your JavaScript to use this plugin:
foundation.core.js
-
foundation.abide.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 |
|
|
The default event to validate inputs. Checkboxes and radios validate immediately. Remove or change this value for manual validation. |
data-label-error-class |
|
|
Class to be applied to input labels on failed validation. |
data-input-error-class |
|
|
Class to be applied to inputs on failed validation. |
data-form-error-selector |
|
|
Class selector to use to target Form Errors for show/hide. |
data-form-error-class |
|
|
Class added to Form Errors on failed validation. |
data-live-validate |
|
|
Set to true to validate text inputs on any value change. |
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);
Based on $el, get the first element with selector in this order:
- The element's direct sibling('s).
- The element's parent's children.
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:
- The
- 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
- The
- 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
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.