Usage
Basic Validation
Form validation requires passing in a validation object with the rules required to validate your form.
$('.ui.form')
.form({
firstName: {
identifier : 'first-name',
rules: [
{
type : 'empty',
prompt : 'Please enter your first name'
}
]
},
lastName: {
identifier : 'last-name',
rules: [
{
type : 'empty',
prompt : 'Please enter your last name'
}
]
},
username: {
identifier : 'username',
rules: [
{
type : 'empty',
prompt : 'Please enter a username'
}
]
},
password: {
identifier : 'password',
rules: [
{
type : 'empty',
prompt : 'Please enter a password'
},
{
type : 'length[6]',
prompt : 'Your password must be at least 6 characters'
}
]
}
terms: {
identifier : 'terms',
rules: [
{
type : 'checked',
prompt : 'You must agree to the terms and conditions'
}
]
}
})
;
Let's go ahead and get you signed up.
Validating Dropdowns
Dropdowns can also be validated like other form fields. Simply match the validation rule to the hidden input associated with the dropdown
$('.ui.dropdown')
.dropdown()
;
$('.ui.form')
.form({
gender: {
identifier : 'gender',
rules: [
{
type : 'empty',
prompt : 'Please enter a gender'
}
]
},
name: {
identifier : 'name',
rules: [
{
type : 'empty',
prompt : 'Please enter your name'
}
]
},
})
;
Gender
Validation with Message
Forms that contain a ui message error block will automatically be filled in with form validation information.
Let's go ahead and get you signed up.
Custom Validation
Custom form validation requires passing in a validation object with the rules required to validate your form.
$('.ui.form')
.form({
dog: {
identifier: 'dog',
rules: [
{
type: 'empty',
prompt: 'You must have a dog to add'
},
{
type: 'contains[fluffy]',
prompt: 'I only want you to add fluffy dogs!'
},
{
type: 'not[mean]',
prompt: 'Why would you add a mean dog to the list?'
}
]
}
})
;
Let's go ahead and get you signed up.
Inline Validation and Validation Events
Validation messages can also appear inline. UI Forms automatically format labels with the class name prompt. These validation prompts are also set to appear on input change instead of form submission.
This example also uses a different validation event. Each element will be validated on input blur instead of the default form submit.
$('.ui.dropdown')
.form(validationRules, {
inline : true,
on : 'blur'
})
;
Let's go ahead and get you signed up.
Behavior
All the following behaviors can be called using the syntax$('.foo').form('behavior name', argumentOne, argumentTwo)
| submit | Submits selected form |
| validate form | Validates form and calls onSuccess or onFailure |
| get change event | gets browser property change event |
| get field(id) | Returns element with matching name, id, or data-validate metadata to ID |
| get validation(element) | Returns validation rules for a given field |
| has field(identifier) | Returns whether a field exists |
| add errors(errors) | Adds errors to form, given an array errors |
Settings
Form Settings
Form settings modify the form validation behavior
| Setting | Default | Description |
|---|---|---|
| keyboardShortcuts | true | Adds keyboard shortcuts for enter and escape keys to submit form and blur fields respectively |
| on | submit | Event used to trigger validation. Can be either submit, blur or change. |
| revalidate | true | If set to true will revalidate fields with errors on input change |
| delay | true | Delay from last typed letter to validate a field when using on: change or when revalidating a field. |
| inline | false | Adds inline error on field validation error |
| transition | scale | Named transition to use when animating validation errors. Fade and slide down are available without including ui transitions |
| duration | 150 | Animation speed for inline prompt |
Validation Rules
Validation rules are a set of conditions required to validate a field
| Name | Arguments | Description |
|---|---|---|
| empty | value | Checks whether a field is empty |
| value | Checks whether a field is a valid email address | |
| length | value | Checks whether a field is longer than or equal to a length |
| not | value, notValue | Checks whether a field is not a value |
| contains | value, text | Checks whether a field contains text |
| is | value, text | Checks whether a field matches a value |
| maxLength | value, maxLength | Checks whether a field is less than or equal to a max length |
| match | value, fieldIdentifier | Checks whether a field matches another field |
| url | value | Checks whether a field is a url |
| checked | - | Checks whether a checkbox field is checked |
Callbacks
Callbacks specify a function to occur after a specific behavior.
| Setting | Context | Description |
|---|---|---|
| onValid | field | Callback on each valid field |
| onInvalid | field | Callback on each invalid field |
| onSuccess | form | Callback if a form is all valid |
| onFailure | form | Callback if any form field is invalid |
Templates
Templates are used to construct elements
| Template | Arguments | Description |
|---|---|---|
| error | Errors (Array) | Constructs the contents of an error message |
| prompt | Errors (Array) | Constructs an element to prompt the user to an invalid field |
DOM Settings
DOM settings specify how this module should interface with the DOM
| Setting | Default | Description |
|---|---|---|
| namespace | form | Event namespace. Makes sure module teardown does not effect other events attached to an element. |
| selector |
selector : {
message : '.error.message',
field : 'input, textarea, select',
group : '.field',
input : 'input',
prompt : '.prompt',
submit : '.submit'
}
|
Selectors used to match functionality to DOM |
| metadata |
metadata : {
validate: 'validate'
},
|
HTML5 metadata attributes |
| className |
className : {
active : 'active',
placeholder : 'default',
disabled : 'disabled',
visible : 'visible'
}
|
Class names used to attach style to state |
Debug Settings
Debug settings controls debug output to the console
| Setting | Default | Description |
|---|---|---|
| name | Form | Name used in debug logs |
| debug | True | Provides standard debug output to console |
| performance | True | Provides standard debug output to console |
| verbose | True | Provides ancillary debug output to console |
| errors |
errors : {
method : 'The method you called is not defined.'
}
|
|