react-redux-easy-form

Main Concepts:

1. Form has to perform in redux-middleware layer, not in components.
2. Total dividing application views and business-logic.
3. Minimum subscriptions and render processes.
4. Maximum usability.
5. Including modern React concepts.
6. Static types (TypeScript).
7. Performs in ReactDOM and ReactNative environments both

Installation

npm i react-redux-easy-form --save

You need react, redux, react-redux, reselect also to be installed.

Configuring redux-store

1import { applyMiddleware, createStore, combineReducers } from 'redux';
2import { easyFormMiddleware, easyFormReducer } from 'react-redux-easy-form';
3
4const rootReducer = combineReducers({
5   forms: easyFormReducer,
6   // ... your reducers
7});
8
9const mws = applyMiddleware(
10  easyFormMiddleware,
11  // your middlewares
12);
13
14const store = createStore(rootReducer, {}, mws);

Initiate Form

1import { FormProvider } from 'react-redux-easy-form';
2// if use TS, the author will recommend to use enums for forms and fields naming
3import { EFormName } from '@src/root-enums';
4
5const ProfileForm = memo(() => {
6   const dispatch = useDispatch();
7
8   const initialValues = useSelector(getProfileFormInitialValues);
9
10   useEffect(() => {
11      dispatch(fetchInitialData());
12   }, []);
13
14   return (
15      <FormProvider
16        initialValues={initialValues}      
17        name={EFormName.Profile}
18      >
19        <AgeField/>
20        <FullNameField />
21        <GenderField />
22      </FormProvider>
23   );
24});

The fields will be bound with form name by React Context API.

Note: FormProvider does not create an element wrapper like form or kind. In this way FormProvider can be used in ReactDOM or ReactNative environment. If you need semantic wrapper, wrap the provider in form-element by yourself.

Note: Form component is deprecated since v2.0.0.

Implement Form Fields

Define Field Config

1import { IFieldConfig } from 'react-redux-easy-form';
2
3const fieldConfig: IFieldConfig = {
4  changeValueGetter: (event) => event.target.value,
5  validateOnChange: true,
6  validators: [
7     (value) => Number(value) > 99 ? 'Must be less than 100' : null,
8  ],
9};

IFieldConfig

Option Name	Option Type	Description
changeValueGetter	(event:any)=>any	A callback, that calls in onChange callback-prop, and transforms input argument into output result to set
validateOnChange	boolean	A boolean flag, which decides to call fieldValidator on each onChange call to immediately receive validation result
validators	TValidator[]	An array of TValidator functions, that validates the field separately. Each validation result will be set as separate element of output array

Call useField Hook Within Your Component

1import { useField } from 'react-redux-easy-form';
2
3const AgeField = memo(() => {
4  const {
5    errors,
6    onChange,
7    value,
8  } = useField<string>(EProfileFieldName.Age, fieldConfig);
9
10  return (
11    <div>
12      <label htmlFor={EProfileFieldName.Age}>
13        Age (years)
14      </label>
15      <input
16        name={EProfileFieldName.Age}
17        onChange={onChange}
18        type="number"
19        value={value ?? ''}
20      />
21      {errors && (
22        <ul>
23          {errors.map((err: string) => (
24            <li key={atob(err)} style={{ color: 'red' }}>{err}</li>
25          ))}
26        </ul>
27      )}
28    </div>
29  );
30});

useField hook returns an object of type TUseFieldSubscription.

TUseFieldSubscription

Name	Type	Description
clear	() => void	A callback, clearing the field value in redux-store
errors	string[], null	An array of field errors, provided after the validators called
isFieldValid	boolean	A boolean value defines that field validation completed with no errors
isPristine	boolean	A boolean value shows that field has had no changes
onChange	(...callbackArgs: any[]) => void	A callback, changing value of an input in redux store
validate	() => void	A callback, triggering the validation process of the field. For example, you can put it in onFocus, or onBlur props of your input
value	any	Current value of the field in forms state of redux store

Action-Creators

Action-Creators starting the middleware

changeValue

changeValue(formName: string, fieldName: string, value: any): Action

Starts a middleware changing form field value. Field status becomes dirty.

changeValueAndValidate

changeValueAndValidate(formName: string, fieldName: string, value: any): Action

Starts a middleware changing form field value and immediately calls the validator on it.

clearValue

clearValue(formName: string, fieldName: string): Action

Starts a middleware clearing the field value. Status becomes dirty.

validateAll

validateAll(formName: string): Action

Starts a middleware launching all validators in the form.

validateField

validateField(formName: string, fieldName: string): Action

Starts a middleware launching all validators for the field.

Flat Action-Creators

clearFieldErrors

clearFieldErrors(formName: string, fieldName: string): Action

Sets the field errors to null

clearFieldValue

clearFieldValue(formName: string, fieldName: string): Action

Sets the form field value to null

initiateForm

initiateForm(formName: string, initialValues: object): Action

setFieldErrors

setFieldErrors(formName: string, fieldName: string, errors: string[] | null): Action

Sets the field validation errors

setFieldStatus

setFieldStatus(formName: string, fieldName: string, status: EEasyFormFieldStatus): Action

Sets the field status

setFieldValue

setFieldValue(formName: string, fieldName: string, value: any): Action

Sets the value into the form field

setFormErrors

setFormErrors(formName: string, errors: string[] | null): Action

Sets the form errors

dropForm

dropForm(formName: string): Action

Clears all values, keeps all initials, and sets all statuses to pristine

Selectors

getForms

Returns forms state branch

createGetForm

createGetForm(formName: string): Selector

Returns the form state by the form name

createGetCommonFormErrors

createGetCommonFormErrors(formName: string): Selector

Returns the form errors (only common errors, except fields errors)

createGetFormAllFieldsErrors

createGetFormAllFieldsErrors(formName: string): Selector

Returns the form fields errors (common form errors not included)

createGetFormErrors

createGetFormErrors(formName: string): Selector

Returns all of the form validation errors

createGetIsFormValid

createGetIsFormValid(formName: string): Selector

Returns a boolean flag, whether the form is valid

createGetFormValues

createGetFormValues(formName: string): Selector

Returns values state branch of the form

createGetFormInitialValues

createGetFormInitialValues(formState: string): Selector

Returns initials state branch of the form

createGetFormStatuses

createGetFormStatuses(formName: string): Selector

Returns statuses state branch of the form

createGetIsFormPristine

createGetIsFormPristine(formName: string): Selector

Returns a boolean flag, whether all of the form fields are in pristine status

createGetFormFieldValue

createGetFormFieldValue(formName: string, fieldName: string): Selector

Returns the form field value (from values state branch)

createGetFormFieldInitialValue

createGetFormFieldInitialValue(formName: string, fieldName: string): Selector

Returns the form field initial value (from initials state branch)

createGetFormFieldErrors

createGetFormFieldErrors(formName: string, fieldName: string): Selector

Returns the form field errors (from errors state branch)

createGetIsFormFieldValid

createGetIsFormFieldValid(formName: string, fieldName: string): Selector

Returns a boolean flag of the validation result of the form field

createGetFormFieldStatus

createGetFormFieldStatus(formName: string, fieldName: string): Selector

Returns the form field status (from statuses state branch)

createGetIsFormFieldPristine

createGetIsFormFieldPristine(formName: string, fieldName: string): Selector

Returns a boolean flag, whether the form field is pristine

createGetFormFieldSafetyValue

createGetFormFieldSafetyValue(formName: string, fieldName: string): Selector

Returns a calculated current value of the form field. The Calculation includes the set value, the initial value and the field status.

createGetFormSafetyValues

createGetFormSafetyValues(formName: string): Selector

An analogue of createGetFormFieldSafetyValue selector-creator, but returns all of the values of the form