This package reduces the boilerplate codes need to manage state for form data, modifying and validating it. It provides two intuitive hooks useFormData and useValidation with clean api. Some of the features it provides are
- Form data can be shared among multiple components without any boilerplate codes.
- Validation state and errors can also be shared among multiple components without any boilerplate codes.
- It usage dotted path of hierarchical form object to modify the value and give flat error object so that is it easer to use with ui events and to show in ui.
- It easily allows you to break form into multiple steps or multiple components. The hook accepts baseDottedPath so that you can only subscribe to part of hierarchical form data and errors.
Click to expand/collapse this section
// useTransactionForm.ts
import { CreateSharedFormDataHookWithCleanUp, CreateSharedFormValidationHookWithCleanUp} from "@devnepal/use-form";
export const InitialData = {
date: null as Date | null,
amount: 0,
user: {
firstName: '',
lastName: '',
email: '',
age: 0,
}
}
export const {hook: useTransactionForm, cleanUp: cleanUpTransactionForm} = CreateSharedFormDataHookWithCleanUp(InitialData);
export const {hook: useTransactionValidation, cleanUp: cleanUpTransactionValidation} = CreateSharedFormValidationHookWithCleanUp(useTransactionForm);Form component One
// ExampleTransactionForm.tsx
import React, { ChangeEventHandler, useEffect } from 'react';
import css from '../story.module.css';
import { useTransactionForm, InitialData, useTransactionValidation } from './useTransactionForm';
import * as yup from 'yup';
const TransactionForm = () => {
const {formData, setFieldValue} = useTransactionForm<typeof InitialData>();
const { registerValidators, errors } = useTransactionValidation();
// register validators
useEffect(() => {
return registerValidators({
amount: yup.number().min(1)
})
}, [])
const setFormValue: ChangeEventHandler<HTMLInputElement> = (e) => {
setFieldValue(e.target.name, e.target.value);
}
return (
<form className={css.form}>
<label htmlFor="date">Transaction Date</label>
<input type="date" name="date" id="date" onChange={setFormValue} value={(formData?.date || '')} />
<label htmlFor="amount">Amount</label>
<input name="amount" id="amount" onChange={setFormValue} value={(formData?.amount || '')} />
<div className={css.errorBlock}>
{
Object.entries(errors).map(([key, value]) => (
<span><br/>{key}: {value}</span>
))
}
<br/>
</div>
</form>
);
}
export default TransactionForm;Form component Two
// ExampleUserForm.tsx
import React, { ChangeEventHandler, useEffect } from 'react';
import css from '../story.module.css';
import {useTransactionForm, useTransactionValidation, InitialData } from './useTransactionForm';
import * as yup from 'yup';
const UserForm = () => {
const {formData: user, setFieldValue} = useTransactionForm<typeof InitialData.user>('user');
const { registerValidators, errors } = useTransactionValidation('user');
useEffect(() => {
return registerValidators({
firstName: yup.string().required().min(2),
lastName: yup.string().required().min(2),
email: yup.string().required().email(),
})
}, [])
const setFormValue: ChangeEventHandler<HTMLInputElement> = (e) => {
setFieldValue(e.target.name, e.target.value);
}
return (
<form className={css.form}>
<label htmlFor="firstName">First Name</label>
<input name="firstName" id="firstName" onChange={setFormValue} value={(user?.firstName || '')} />
<label htmlFor="lastName">Last Name</label>
<input name="lastName" id="lastName" onChange={setFormValue} value={(user?.lastName || '')} />
<label htmlFor="email">Email</label>
<input name="email" id="email" onChange={setFormValue} value={(user?.email || "")} />
<div className={css.errorBlock}>
{
Object.entries(errors).map(([key, value]) => (
<span><br/>{key}: {value}</span>
))
}
<br/>
</div>
</form>
);
}
export default UserForm;Note on
registerValidators
- It should be called from useEffect to register validators related to current component
- It returns a function which can be called to unregister validators. Returning the function from useEffect removes these validators when components are unmounted
- validator passed to registerValidator can also be a function that returns error message when data is invalid and empty text otherwise.
Root Component
// MultiStepForm.tsx
import React, { useState } from 'react';
import UserForm from './ExampleUserForm';
import TransactionForm from './ExampleTransactionForm';
import { useTransactionValidation, cleanUpTransactionForm, cleanUpTransactionValidation } from './useTransactionForm';
const MultiStepForm = ({}) => {
const [curStep, setCurStep] = useState(0);
const { isValid } = useTransactionValidation();
// clean-up when root component is unmounted
useEffect(() => {
return () => {
cleanUpTransactionForm();
cleanUpTransactionValidation();
}
}, []);
const changeStep = (step: number) => {
setCurStep((oldStep) => {
const newStep = oldStep + step;
if (newStep >= 0 && newStep < 2) {
return newStep
}
return oldStep;
})
}
return (
<div>
{ curStep === 0 && <UserForm />}
{ curStep === 1 && <TransactionForm />}
<div>
<button onClick={() => changeStep(-1)} >Prev</button>
<button onClick={() => changeStep(1)} disabled={!isValid}>Next</button>
</div>
</div>
)
}
export default MultiStepForm;Click to expand/collapse this section
import {useFormData, useValidation} from "./index.ts";
...
// inside your component
const {formData: user, setFieldValue} = useFormData<typeof InitialData.user>(initialData, 'user');
const { registerValidators, errors } = useValidation(user, 'user');
...When hook is scoped with base path (eg. user in above example) we can use relative path to access formData or errors eg. we can use 'firstName' instead of 'user.firstName'
Click to expand/collapse this section
To use it in only one form you don't need to create a separate module. Instead you can directly use hooks with initial data
import {useFormData, useValidation} from "./index.ts";
...
// inside your component
const {formData: user, setFieldValue} = useFormData<typeof InitialData.user>(initialData, 'user');
const { registerValidators, errors } = useValidation(user, 'user');
useEffect(() => {
return registerValidators({
firstName: yup.string().required().min(2),
lastName: yup.string().required().min(2),
email: yup.string().required().email(),
})
}, []);
...Click to expand/collapse this section
To get type hints on your IDE pass generic type parameters as shown in following example.
import {useFormData, useValidation} from "./index.ts";
...
// inside your component
const {formData: user, setFieldValue} = useFormData<typeof InitialData.user>(initialData, 'user');
const { registerValidators, errors } = useValidation<typeof validators>(user);
const validators = {
firstName: yup.string().required().min(2),
lastName: yup.string().required().min(2),
email: yup.string().required().email(),
};
useEffect(() => {
return registerValidators(validators)
}, []);
...Click to expand/collapse this section
You can use simple function as validator. The function will be called with flatFieldName, valueToValidate, formData and it should return error message if the data is invalid otherwise return empty string.
Note Scope hooks with basePath parameter In previous examples hooks were scoped using basePath parameter eg.
const { registerValidators, errors } = useTransactionValidation('user');. When basePath is not used we need to use dotted path like belowuser.firstName
const { registerValidators, errors } = useTransactionValidation();
useEffect(() => {
return registerValidators({
'user.firstName': (fieldName: string, value: string) => (!!value ? '' : 'First name is required'),
'user.lastName': (fieldName: string, value: string) => (!!value ? '' : 'Last name is required'),
'user.age': (fieldName: string, age: number) => (age > 0 ? '' : 'Age should be greater than 0'),
'amount': (fieldName: string, amount: number) => (amount > 0 ? '' : 'Amount should be greater than 0'),
});
}, []);