standard validation module that enables you to implement high interactive validation web-components and framework components with zero effort. Try the interactive validation demos.
- Modular so it can be used anywhere. Demo
- Support regex & custom validation function. Demo
- Reactive and customizable. Demo
- Support async validations. Demo
- Fast & reliable.
- Integrate with jb-form to make zero. Validation demo
- Config form with highly customizable validation methods.
npm install jb-validationjb-validation is framework-agnostic and does not ship a separate React wrapper. Import ValidationHelper from jb-validation in a hook or service and connect its callbacks to component state. The interactive demos show the same API used from a React story.
- Synchronous validation
- Async and deferred validation
- Dynamic validation getter
- Manual/server error
- Reset validation state
jb-validation is a universal validation module that let you simplify validations process. Architecture demo
to achieve our goal we make jb-validation Async first mean checkValidation return Promise by default, despite all your validations were sync or not.
in 90% of front-end use cases we just need sync Validation in our component or in our apps so we recommend you to use sync methods for your default useCases in front-end components and add some async methods beside them for more complex use cases. but in other scenario like web-services and etc please use Async first approach.
here we have ValidationHelper class that is a base class of our validation system. in every component or module that want to implement jb-validation first we have to create a instance of ValidationHelper class and then infract with it.
this document have 2 sections:
- how to interact with already implemented module inside any component.
- how to implement jb-validation in a new component.
before we start to see how to use validations methods we must get familiar with some types in jb-validation:
a regex or function that test value and return true/false or string or Promise<boolean | >.
single validation item with validator AND A default error message in case of invalidity and other meta data like validation type & defer.
list of validation Item to validate your value with. if value pass all the list validators it's considered as a valid value.
validation value is the value you need for your validator functions parameter. it's may be the same with component value or it may be different with it. for example in jb-date-input value is date ISO string like 2024-05-11 but in our validator we need more data to validate the date like Date object so we define it in our ValidationValue type.
in every web-component that support jb-validation as a validation method you
must follow 3 step 1- provide a validation list(contain validator and message)
2- call check validation method
3- check the result
its easy and straight forward like the synchronous validation example:
component.validation.list = [
{
validator: /.{3}/g,
message: "your value must have at least 3 char",
},
];
//check validity and get the result
//sync result will ignore async validator or async value
const result = component.validation.checkValiditySync({showError:true});
//async validator that also support async validation getter and async validator function. will return promise
const asyncResult = component.validation.checkValidity({showError:true});
//do whatever you want with the result
console.log("isInputValid:", result.isAllValid);
asyncResult.then((asyncResultData)=>{console.log("isInputValid:", asyncResultData.isAllValid);})there is 2 way to provide a validation to the module 1- provide a validation list directly by an array of validator
component.validation.list = [
{
validator: /.{3}/g,
message: "your value must have at least 3 char",
},
];2- register a function that return validation list:
const getValidations = () => {
return [
{
validator: /.{3}/g,
message: "your value must have at least 3 char",
},
];
};
component.validation.addValidationListGetter(getValidations);in the second method getValidations is called on each validation check; see the dynamic getter demo. If you have complex validation logic that may change based on your app states
or component states it's better to use second way to make sure everything is
controlled.
remember both way can be used together and you can even add multiple
ValidationListGetter in more complex situations.
validations in jb-validation follow this typescript type:
//ValidationValue will be different based on the implementor component
export type ValidatorFunction<ValidationValue> = (
value: ValidationValue,
) => boolean | string | Promise<boolean | string>;
export type ValidationItem<ValidationValue> = {
/**
* @property validation function or regex to match value with
*/
validator: RegExp | ValidatorFunction<ValidationValue>;
/**
* @property error message that will be shown if validator return false or regex failed
*/
message: string;
/**
* @property type of error (category) its optional
*/
stateType?: keyof ValidityStateFlags;
/**
* @property defer validator execution until all non-deferred validation executed.(good for async validator)
*/
defer?: boolean;
};it means you can pass a regex or function as a validator and there is a optional stateType that indicate which standard has been violated.
Use a function when validation depends on application state or needs a custom message. Demo
function validator have many benefits one of them is that they may be defined in a scope that contain your app states and variables (like in react components or hooks or angular class). it means that you can access your own app variables and write a logic in your function based on your need. for example:
function setValidations(validStudentList = []) {}
component.validation.list = [{
validator: (student) => validStudentList.includes(student),
message: "this student is not in our valid student list",
}];the other benefits is that you can have very complex logic for your input
because its just a plain function and if you return string instead of
boolean we assume it as an Error message and show it to the user.
function setValidations(blackList = []) {}
component.validation.list = [{
validator: (studentName) => {
if (blackList.includes(studentName)) {
return `${studentName} is in the black list try someone else`;
}
return true;
},
message: "this message will shown if you return false",
}];Return a promise for server checks or expensive validation and use defer: true when it should run only after synchronous rules pass. Demo
you can also set async validator function to check validation with your server or doing heavy search. to achieve this you just have to return promise in your validator function.
function setValidations(validStudentList = []) {}
component.validation.list = [{
validator: ({ displayValue, value }) => {
return new Promise((resolve) => {
isEmailTaken(value).then(({ isTaken, suggestionMail }) => {
if (isTaken) {
if (suggestionMail) {
//invalid value with custom message
resolve(`${value} is taken. but you can pick ${suggestionMail}`);
} else {
//invalid value with default message
resolve(false);
//we don't support promise reject so please always resolve your promise.
}
} else {
// valid value
resolve(true);
}
});
});
},
message: "email is already taken",
// will wait for all non async validation to be valid then execute. if not set it may cause delay in validation display even for sync validation
defer:true,
}];remember all async validator will be executed after sync one and deferred validation will only execute when all non-deferred one were valid. so if you want your async validator does not execute until all other validator passes, set defer:true so it will execute when all other validation is passed.
Leave validator undefined to represent a manual or server-side error. Demo
if you leave validator undefined it means value is always invalid this could help you when you want to show error message based on a external reason (server side error or to showing other validation libraries error).
component.validation.list = [{
message:'server cant respond now',
}]if you have a web-component and you want to ad jb-validation support to it you just have to create a instance of ValidationHelper in your component. See the validation demo for the complete interaction.
after that just pas some callbacks function that jb-validation need to interact with your component and then you will have the validation support into your web-component.
ValidationHelper is framework-agnostic and can be used directly from React, Vue, Angular, or a custom element. The interactive examples use the same public API.
| member | type | description |
|---|---|---|
list |
ValidationItem[] |
Explicit validation rules. Assigning a list immediately starts a silent validation pass. Demo |
result |
ValidationResult | null |
Most recent full validation result. Demo |
resultSummary |
{ isValid: boolean | null; message: string | null } |
Compact status and first error message. Demo |
checkValidity(parameters?) |
Promise<ValidationResult> |
Runs synchronous and asynchronous rules. Demo |
checkValiditySync(parameters?) |
ValidationResult |
Runs only synchronous rules. Demo |
addValidationListGetter(getter) |
void |
Adds rules generated at validation time. Demo |
setCallbacks(callbacks) |
void |
Registers value, result, and error-display callbacks. Demo |
reset() |
void |
Clears the last result, summary, and displayed error. Demo |
Set showError: false when the caller wants to inspect a result without displaying the first validation message. Pass value to validate a value other than the callback-provided current value.
-
see jb-form if you want to manage a group of inputs with jb-validation integrated component.
-
see All JB Design system Component List for more components
-
use Contribution Guide if you want to contribute in this component.