onSubmit
Quickstart | API | Examples | Codesandbox | Demo
Description
onsubmit is the simplest, least set-up needing way to validate an input or a form. On the client or on the server.
Features
- Light-weight. (~1KB gzipped)
- Simple API.
- Zero dependencies.
Install
npm i onsubmitQuickstart
import { validateField } from 'onsubmit';
const firstNameRules = {
required: { criterion: true, message: 'First Name is required' },
minLength: { criterion: 3, message: 'Minimum length is 3' },
maxLength: { criterion: 10, message: 'Maximum length is 10' },
};
// recieve an array of errors
const errors = validateField('Ammar', 'firstName', firstNameRules);API
Methods
| Function | Description | Parameters | Returns |
|---|---|---|---|
validateField |
Validates a single form field against specified rules. |
value: The string value of the field. name: Name of the field.rules: Object containing validation rules. |
Array of FieldError objects, each containing the name of the field and the error message. |
validateForm |
Validates an entire form. |
values: A key-value pair object of field names and values.rules: A key-value object which maps field names to their rules . |
Array of FieldError objects for the entire form. |
Validation Rules
| Rule | Description | Expected Value |
|---|---|---|
minLength |
Minimum length of the field's value. | Number (length) |
maxLength |
Maximum length of the field's value. | Number (length) |
pattern |
Regex pattern the field's value should match. | RegExp |
custom |
Custom validation logic. | Function |
required |
Whether the field is required. | Boolean |
Examples
Validate a single field
import { validateField } from 'onsubmit';
const emailRules = {
required: { criterion: true, message: 'Email is required' },
pattern: {
criterion: /^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,4}$/,
mesaage: 'Invalid email',
},
};
const errors = validateField('ammar@winenergy.co' , 'email', emailRules);Custom validation logic
import { validateForm } from 'onsubmit';
const rulesObject = {
custom: {
criterion: (value) => value === password,
message: 'Passwords do not match',
}
};
const errors = validateField(passwordRepeat, 'passwordRepeat', rulesObject);Validate some data
import { validateForm } from 'onsubmit';
const rulesObject = {
minLength: { criterion: 3, message: 'Minimum length is 3' },
maxLength: { criterion: 10, message: 'Maximum length is 10' },
pattern: { criterion: /^[a-z]+$/, message: 'Only lowercase letters allowed' },
custom: { criterion: (value) => value !== 'example', message: 'Value cannot be "example"' },
required: { criterion: true, message: 'Field is required' },
};
const data = {
firstName: 'Ammar',
lastName: 'Halees',
email: 'ammar@company.co',
};
const errors = validateForm(data, rulesObject);Validate a form
import { validateForm } from 'onsubmit';
const handleOnsubmit = (e) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);
const data = Object.fromEntries(formData);
const errors = validateForm(data, RulesMap);
};Utils and patterns
utils
onsubmit provides a set of utility functions and patterns to help you build your forms.
| Function Name | Type Signature | Description |
|---|---|---|
isDateObject |
(value: unknown) => value is Date |
Checks if the given value is a valid Date object. |
isString |
(value: unknown) => value is string |
Determines if the provided value is a string. This includes both string literals and String objects. |
isNumber |
(value: unknown) => value is number |
Verifies if the value is a number and is finite. |
isNullOrUndefined |
(value: unknown) => value is null | undefined |
Checks if the value is either null or undefined. |
isObject |
<T extends object>(value: unknown) => value is T |
Determines if a value is an object. This excludes null, arrays, and Date objects. |
isFile |
(element: HTMLInputElement) => element is HTMLInputElement |
Checks if an HTML input element is of type file. |
_patterns
emailurialphanumericcuidkebabCasearabic
FAQ
Which rule object has precedence?
The required rule has the highest precedence. The remaining rules are evaluated in the order they are specified in the rulesObject.
Types
type Criterion = string | number | CustomFunction | boolean | RegExp;
interface Rule {
criterion: Criterion;
message: string;
}
type FormDataShape = KeyValuePair | { [k: string]: FormDataEntryValue };
interface RulesObject {
required?: Rule;
minLength?: Rule;
maxLength?: Rule;
pattern?: Rule;
custom?: Rule;
}TODO
-
onlySecureopt-out rule. -
minDaterule. -
maxDaterule. -
minTimerule.rule -
maxTimerule -
filerule: { minSize, maxSize, type, name } -
cardNumberpattern. -
cardCompanyutility. - Benchmarking
- Allow for multiple patterns