@prototyp/skeleform
v1.0.2
Published
React/React-Native form management utility
Downloads
115
Readme
skeleform
Form management and validation toolkit originally a part of https://github.com/prototypdigital/skeletor
Usage
Handle form value updates and validation with useForm
. Full TypeScript support, ability to configure optional parameters, custom validation rules.
Flexible in its function, supports multiple validation approaches through callbacks:
- For on-change validation, use
update("prop", value, true)
- To trigger standalone validation, use
validate("prop")
- Validate entire form with
validateForm()
The order of importance when it comes to validating fields is:
- Custom validation rule - will get the value as-is for your rule to validate it fully. The configuration rule receives the current value, state and optional flag values for you to validate against.
- If there is no custom validation rule and the primitive value check returns false (there is no value), check if the field is optional. If optional, the validation result is
true
, otherwise it isfalse
; - If all previous checks have not been triggered, return the primitive "has value" check result. This will return
false
for values such as:null | undefined | NaN | "" | Invalid Date
. This will returntrue
if you have a complex value type such asobject | Array
, so in case you have a complex value type use a custom validation rule to get what you need.
Example 1: Simple use case with standalone validation on blur:
const {state, validation, update, validate} = useForm({email: "", password: "");
...
<input
...
value={state.email}
onChange={(e) => update("email", e.currentTarget.value)}
onBlur={() => validate("email")}
/>
...
Example 2: Simple use case with on-change validation:
// See example 1
...
onChange={(e) => update("email", e.currentTarget.value, true)}
...
Example 3: Simple use case with on-submit validation:
// See example 1
function submit() {
if(!validateForm()) {
// Throw invalid error
// validation object will be populated
}
}
...
<input
...
value={state.email}
onUpdate={(e) => update("email", e.currentTarget.value)}
/>
<button onPress={submit}>Submit</button>
Validation has three possible values:
undefined
= validation of the field value has not been done yet.false
= validation has failed, the state value is not considered valid.true
= validation has succeeded, the state value is considered valid.
What does that mean? Well, it means that when you have validation.email === false
, you should show an error message on the field. undefined | true
are not relevant for rendering, only functionally to block form submit events.
Example 4: Form configuration
const { state, validation, update, validate } = useForm(
{ firstName: "", middleName: "", lastName: ""},
{
// If left empty, validation.middleName will be true
optional: ["middleName"],
// validation.lastName is invalid if lastName is <3 characters long
// state can be used to compare with other values (ie repeat password)
rules: { lastName: (value, state, optional) => value.length >= 3,
}
Example 5: useFormUtils
Utility functions to help with standalone state validation, such as when re-validating a list of form values in a parent components.
const { stateValidation } = useFormUtils<Person>();
function validatePeople() {
return people.every(person => stateValidation(person).valid);
}
Other utilities: doesValueExist
, validateByRule
, isOptional
, fieldValidation
, stateValidation
. Some are meant for internal useForm
usage, such as fieldValidation
and validateByRule
, but are not unusable.