Awesome
Form validation for react-bootstrap.
Feedback, suggestions and pull-requests are welcome!
Example 1: Simple Registration Form
import React from 'react';
import { ButtonInput } from 'react-bootstrap';
// Import Form and ValidatedInput components. Notice that you need to use
// this ValidatedInput component instead of the original one to have
// validation and other features working
import { Form, ValidatedInput } from 'react-bootstrap-validation';
// There's also a wrapper for radio inputs that react-bootstrap
// doesn't (yet) have
import { Radio, RadioGroup } from 'react-bootstrap-validation';
class MyRegistrationForm extends React.Component {
...
render() {
return (
<Form
// Supply callbacks to both valid and invalid
// submit attempts
onValidSubmit={this._handleValidSubmit.bind(this)}
onInvalidSubmit={this._handleInvalidSubmit.bind(this)}>
<ValidatedInput
type='text'
label='Email'
// Each input that you need validated should have
// the "name" prop
name='email'
// Validation rules separated with comma
validate='required,isEmail'
// Error messages for each error type
errorHelp={{
required: 'Please enter your email',
isEmail: 'Email is invalid'
}}
/>
<ValidatedInput
type='password'
name='password'
label='Password'
// You can pass params to validation rules
validate='required,isLength:6:60'
errorHelp={{
required: 'Please specify a password',
isLength: 'Password must be at least 6 characters'
}}
/>
<ValidatedInput
type='password'
name='password-confirm'
label='Confirm Password'
// Validate can be a function as well
validate={(val, context) => val === context.password}
// If errorHelp property is a string, then it is used
// for all possible validation errors
errorHelp='Passwords do not match'
/>
{/* Custom component to supply a couple of bootstrap
wrappers around radio inputs to look pretty */}
<RadioGroup name='radio'
value='3'
label='Which one is better?'
// Supports validation as well
validate={v => v === 'cola'}
errorHelp='Pepsi? Seriously?'
// And accepts (almost) all the same props
// as other react-bootstrap components
labelClassName='col-xs-2'
wrapperClassName='col-xs-10'>
{/* Radio is a simple wrapper around react-bootstrap's
Input component */}
<Radio value='cola' label='Cola' />
<Radio value='pepsi' label='Pepsi' />
</RadioGroup>
<ValidatedInput
type='checkbox'
name='agree'
label='I agree to the terms and conditions'
// Validation rules is easily extendable to fit
// your needs. There are only two custom rules,
// 'isChecked' and 'required', others are stock
// validator.js methods
validate='isChecked'
/>
<ButtonInput
type='submit'
bsSize='large'
bsStyle='primary'
value='Register'
/>
</Form>
);
}
_handleValidSubmit(values) {
// Values is an object containing all values
// from the inputs
}
_handleInvalidSubmit(errors, values) {
// Errors is an array containing input names
// that failed to validate
}
...
}
Example 2: Validating With Schema
In case you have an external validation schema, there are a couple of methods that allow you to use it. Consider the following example with revalidator:
...
import revalidator from 'revalidator';
// Simple revalidator schema with two fields
let schema = {
properties: {
email: {
type: 'string',
maxLength: 255,
format: 'email',
required: true,
allowEmpty: false
},
password: {
type: 'string',
minLength: 8,
maxLength: 60,
required: true,
allowEmpty: false
}
}
};
class MyLoginForm extends React.Component {
...
render() {
return (
<Form
// Provide a validation method for the whole
// form values object. This way inputs will only
// be validated upon submit.
validateAll={this._validateForm.bind(this)}
onValidSubmit={this._onSubmit.bind(this)}>
<ValidatedInput type='text'
label='Email'
name='email'
errorHelp='Email address is invalid'/>
<ValidatedInput type='password'
name='password'
label='Password'
errorHelp='Password is invalid'/>
...
</Form>
);
}
_validateForm(values) {
let res = revalidator.validate(values, schema);
// If the values passed validation, we return true
if (res.valid) {
return true;
}
// Otherwise we should return an object containing errors
// e.g. { email: true, password: true }
return res.errors.reduce((errors, error) => {
// Set each property to either true or
// a string error description
errors[error.property] = true;
return errors;
}, {});
}
...
}
Components
Form
Form is a wrapper around all the inputs.
Properties
onValidSubmit: Function required
Callback that receives values object, which is a hash map of inputName => inputValue.
<Form onValidSubmit={values => alert(`Hello ${values.name}!`)}>
<ValidatedInput name="name" />
...
</Form>
onInvalidSubmit: Function
Callback that is called when there was form submit event and form did not pass the validation. Receives two params: errors: Array and values: Object.
<Form onValidSubmit={values => alert(`Hello ${values.name}!`)}
onInvalidSubmit={(errors, values) => {
alert(`Following fields are invalid: ${errors.join(', ')}`);
}}>
<ValidatedInput name="firstName" validate="required"/>
<ValidatedInput name="lastName" validate="required"/>
...
</Form>
model: Object
Accepts a hash map of initial form values.
<Form onValidSubmit={values => alert(`Hello ${values.name}!`)}
model={{
firstName: 'Jon',
lastName: 'Snow'
}}>
<ValidatedInput name="firstName" validate="required"/>
<ValidatedInput name="lastName" validate="required"/>
...
</Form>
validateOne: Function
If present, this callback is called when field needs to be revalidated -- either when form is submitted or input's onChange event is fired. Receives following arguments: inputName: String, inputValue: String|Boolean|FileList and context: Object. Result is expected in the same format as in the ValidatedInput's validate callback. Useful for validation with external schema.
function validateInput(name, value, context) {
if (!SomeExternalSchema.validate(name, value, context)) {
return '';
}
return true;
}
...
<Form onValidSubmit={this._onSubmit.bind(this)}
validateOne={validateInput}>
...
</Form>
validateAll: Function
If present, this callback is called instead of field by field validation. Receives one argument: values: Object. Should return true if data is successfully validated, otherwise errors hash map of fieldName => errorText. If no specific error text is available, boolean true is allowed instead of string errorText.
<Form onValidSubmit={this._onSubmit.bind(this)}
validateAll={values => {
// Force validation failure, return errors object.
return {
email: true,
firstName: 'First name is invalid'
};
}}>
...
</Form>
errorHelp: String|Object
When validation error is triggered and there's no errorHelp property specified for the validated input, the error text is looked up in form's errorHelp property.
validationEvent: String
Input event that triggers field validation. Can be one of onChange, onBlur or onFocus. Default value is onChange.
ValidatedInput
An extension of react-bootstrap's Input component. Should be used instead of the original one for all the fields that need to be validated. All ValidatedInputs should have name property defined.
Properties
name: String required
This property is inherited from Input with only difference that it is required for ValidatedInput.
validationEvent: String
Event that triggers validation. Can be one of onChange, onBlur or onFocus. Default value is onChange. Overrides Form's validationEvent property.
<ValidatedInput
name='email'
validationEvent='onBlur'
validate='required,isEmail'
/>
validate: Function|String
Either a validation function or a string validation rule.
Validation function receives two arguments, val and context. First one is the value of the input, second one is an object, containing values of all form fields. Having context is useful if you have a field, whose validation depends on other values of the form.
<ValidatedInput
name='passwordConfirm'
validate={(val, context) => {
return val === context.password;
}}
/>
The result of the function should be either a boolean or a string. Any value returned that !== true is considered an error. If string is returned, it is used as an errorHelp property to render the error.
Validation rule is a combination of validator.js method names separated with comma.
<ValidatedInput
name='email'
validate='required,isEmail,isLength:5:60'
/>
In the example above, input's value will be validated with three methods. isLength method also receives additional params. Inverse rules (like !isNull) are supported, although in errorHelp object they're looked up without the exclamation mark.
errorHelp: Object|String
Can be either a string with error text or an object with map ruleName => errorText.
<ValidatedInput
name="email"
validate='required,isEmail',
errorHelp={{
required: 'Please enter your email',
isEmail: 'Invalid email'
}}
/>
If errorHelp property is omitted, default messages are looked up from errorHelp property of Form element.
Radio
Radio component is basically the same as ValidatedInput, except it can not be validated. Validation is performed in the RadioGroup.
RadioGroup
Wrapper component for Radio elements that performs validation and easy default value setup.
Properties
Following properties are inherited from original react-bootstrap Input:
standalone, hasFeedback, bsSize, bsStyle, groupClassName, wrapperClassName, labelClassName
And the next ones are from ValidatedInput:
validate, errorHelp
<RadioGroup name='radio'
// Set the initial value
value='1'
label='Some random options'
labelClassName='col-xs-2'
wrapperClassName='col-xs-10'>
<Radio value='1' label='Option 1' />
<Radio value='2' label='Option 2' />
<Radio value='3' label='Option 3' />
</RadioGroup>
validationEvent: String
This property is a slightly different from ValidatedInputs one - it only accepts onChange (which is also it's default value) and should not be used.
Validators
Validator
A validator.js object extended with the following custom validation methods:
Validator.required(val: String)
Returns true if the value is not null. Can be used as an alias to !isNull validation rule.
Validator.isChecked(val: String)
Used only for checkboxes as their value is return as boolean by the Form component. Returns true if the value equals to 'true'. This is because all the values coming to validator.js methods are treated as strings.
Refer to validator.js documentation for more information on it's validation methods and how to extend it.
FileValidator
An object similar to the validator.js with extend(name, func) method and packed with file validation helpers. This validator is used for all input[type=file] in your form. Every validation method accepts FileList object as files param.
import { FileValidator } from 'react-bootstrap-validation';
...
<ValidatedInput
ref="file"
name="file"
type='file'
label='Attachments'
multiple
validate={files => {
if (FileValidator.isEmpty(files)) {
return 'Please select a file';
}
if (!FileValidator.isFilesCount(files, 1, 3)) {
return 'You can select not more than 3 files';
}
if (!FileValidator.isTotalSize(files, 1048576)) {
return 'Total size must be at least 1MB';
}
if (!FileValidator.isEachFileSize(files, 0, 1048576)) {
return 'Each file must not be larger than 1MB';
}
if (FileValidator.isExtension( files, [ 'exe', 'cmd', 'bat',
'com', 'vbs', 'vbe', 'js', 'jse', 'wsf', 'wsh', 'msc' ])) {
return 'Executable files are not allowed';
}
return true;
}}
/>
Available methods:
FileValidator.isEmpty(files: FileList)
Returns true if there are no files in file list.
FileValidator.isSingle(files: FileList)
Returns true if files count equals to 1.
FileValidator.isMultiple(files: FileList)
Returns true if files count is more than 1.
FileValidator.isFilesCount(files: FileList, min: Number, [max: Number])
Returns true if files count is within allowed range. If max is not supplied, checks if files count equals min.
FileValidator.isTotalSize(files: FileList, min: Number, [max: Number])
Returns true if total size of all files is within allowed range.
FileValidator.isEachFileSize(files: FileList, min: Number, [max: Number])
Returns true if each file's size is within allowed range.
FileValidator.isExtension(files: FileList, extensions: Array)
Returns true if each file's extension is in the extensions array.
FileValidator.isType(files: FileList, types: Array)
Returns true if each file's mime type is in the types array.
Tests
Tests are written using the Jest unit testing framework by facebook. https://facebook.github.io/jest/
To run the tests simply use the command "npm test". All tests should compile and pass before a pull request is accepted.
For new features please add a new unit test spec to the tests directory. Contributions for existing test specifications are welcome.
License (MIT)
The MIT License (MIT)
Copyright (c) 2015 Ivan Reshetnikov (keenn2007@gmail.com)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.