react-form

A context & hook based react form. Supports dirty-check, validation, reset and save functionalities of form

Features

• Dirty Checking

  • Dirty checks for both individual fields and whole form
  • Marks current values as pristine on successful submit
  • Single method tp reset the complete form to last known pristine values

• Validation

  • Supports writing your own custom validation rules
  • Live validation at both individual field level and whole form level
  • Does not check for required field errors until first submit
  • Live validation for required fields after first submit

• General

  • Supports changing the initial form data
  • Pure API, can be integrated with all available UI libraries seamlessly
  • Small size, tree-shakable and no dependancies

Installation

1 npm i --save @avcs/react-form

Documentation

1useForm: ReactHook
2
3arguments: [{
4  // initial form object
5  formData: { [string | symbol]: any };\
6  // Optional Event handler if you want to listen to changes in form
7  onFormChange?: (formMeta: { isFormDirty: boolean, formData: { [string | symbol]: any } }) => void;
8  // Optional Event handler if you want to listen to changes in form errors
9  onErrorChange?: (errorMeta: { hasErrors: boolean, errors: { [string | symbol]: any } }) => void;
10}]
11
12returnValue: {
13  /* Handle submit action, accepts 2 params onSubmit & onError. validates required errors
14   *     any changes from this state will be considered dirty in future
15   *   will execute onSubmit if there are no errors
16   *   will mark the form as pristine if onSubmit returns anything other than false
17   *   will execute onError if there are any errors
18   */
19  handleSubmit: (
20    onSubmit: (formData: { [string | symbol]: any }) => any,
21    onError: (errors: { [string | symbol]: any }) => any
22  ) => void;
23
24  // Resets the form to last known pristine state
25  clearForm: () => void;
26
27  /* Provider to wrap any child components with,
28   *   so that they and useFormState in them can access FormContext
29   *
30   * If using useFormState in the same component where useForm is used,
31   *   this can be passed in options.provider to useFormState
32   */
33  FormProvider: React.Element
34}

1useFormContext: ReactHook
2
3returnValue: {
4  // Same as useForm except FormProvider
5}

1useFormState<T>: ReactHook
2
3arguments: [
4  // key to identify which value from form,
5  //   this field is associated with
6  key: string | symbol,
7  // Options for this field
8  {
9    // default value is applied if the key doesn't exist in the initial form
10    defaultValue?: any,
11    // validate the value and return error or undefined if no errors
12    validate?: (value: any) => any | undefined,
13    // Validates value for required on submit, if true
14    required?: boolean,
15    // Error info to record when there is a require error
16    requiredErrorMessage?: any,
17    // Pass the Provider manually if this hook is not used inside a component thats wrapped in Provider
18    provider?: React.Element
19  }
20]
21
22returnValue: [
23  // current state of the field
24  state: T,
25  // setState method for the field
26  setState: ReactSetState<T>,
27  // true if current state of the field is
28  //   different from last known pristine state
29  isDirty: boolean,
30  // error info if the state is not valid
31  error: any,
32]

Please note: error is any instead of string, this is there so you can pass anything.

Example: You can pass reference to the error node so you can scroll to specific error when clicking submit

Usage

Can be used in 2 different formats. Form & Fields in a single component or in separate components, please refer below for an example of both the use cases

Form

1// Form.tsx
2import React from 'react';
3import { useForm } from '@avcs/react-form';
4
5const Form = () => {
6  const {
7    handleSubmit, clearForm, FormProvider
8  } = useForm({ formData: initialForm });
9
10  // using useFormField in the same component as useForm
11  // check how we are passing provider here but not in FormField component
12  const [field, setField, isFieldDirty, fieldError] = useFormField(key, {
13    defaultValue:  'some value',
14    validate:  (value)  =>  {
15      if  (value !==  'some value')  return  'some error';
16    },
17    required:  true,
18    requiredErrorMessage:  'this field is required',
19    provider: FormProvider
20  });
21
22  const handleChange = useCallback((e) => {
23    setData(e.target.value);
24  }, []);
25
26  const submitForm = useCallback((e) => {
27    handleSubmit(
28      formData => {
29        // API call to save data
30      },
31      errors => {
32        // Process errors
33      }
34    );
35  }, []);
36
37  return (
38    <form>
39      {/* OPTION 1: using form fields separately,
40          see below for definition of FormField */}
41      <FormProvider>
42        <FormField />
43      </FormProvider>
44
45      {/* OPTION 2: using form field in same component as form */}
46      <input type="text" onChange={handleChange} value={field}  />
47
48      <button onClick={submitForm}>Submit</input>
49      <button onClick={clearForm}>Clear</button>
50    </form>
51  );
52};
53
54export default Form;

FormField

1  import React from 'react';
2  import { useFormState } from '@avcs/react-form';
3
4  const FormField = () => {
5    const [data, setData, isDirty, error] = useFormState(key, {
6      defaultValue: 'some value',
7      validate: (value) => {
8        if (value !== 'some value') return 'some error';
9      },
10      required: true,
11      requiredErrorMessage: 'this field is required',
12    });
13
14    const handleChange = useCallback((e) => {
15      setData(e.target.value);
16    }, []);
17
18    return (
19      <input type="text" onChange={handleChange} value={data} />
20    );
21  };
22
23  export default FormField;

Performance

• useForm: re-renders once per load, submit, reset
• useFormContext: re-renders once per load
• useFormField: re-renders once per load, submit, reset, value-change
• onFormChange: triggers once per value-change
• oErrorChange: triggers once per error-change (adding a new error, clearing an error)