With-controlled-form

This library helps you to convert presentational Forms to state controlled forms and add validations on a easy and fast way.

Installation

Run the following command:

npm install with-controlled-form --save

How to use ?

You have two options to choose: use a HOC (High Order Component) or a React Hook.

Use the WithControlledForm HOC

This HOC revives 3 parameters:

• The UI Form component
• The initial state of the form
• The validations of the form

And returns a new controlled form component ready to use.

Example:

import { WithControlledForm } from 'with-controlled-form';

// Setup of the initial state of the component
const initialState = {
  email: '',
  phoneNumber: '',
};

// Add validations easly!
const formValidations = {
  email: {
    isRequired: true,
    isMinLength: 3,
    isMaxLength: 60,
    // You can add custom messages!
    isEmail: [true, 'The emails must be valid value!'],
  },
  phoneNumber: {
    isRequired: true,
    isMinLength: 6,
    isMaxLength: 15,
  }
};

// Get the Form with controlled behaivor
const FormWithControlled = WithControlledForm(Form, initialState, formValidations);

<FormWithControlled handleSubmit={() => alert('done!')} />

In order to correct behavior, the state and validators keys names must be the equals as you can see on the example above.

In your Form component you will recive the state values and handle events functions as props:

const Form = ({
  values,
  errors,
  handleChange,
  handleBlur,
  handleSubmit
}) => (
  <form onSubmit={handleSubmit}>
    <div className="form-element">
      <label htmlFor="email">Email:</label>
      <input
        className="input"
        type="text"
        id="email"
        name="email"
        value={values.email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      <div className="error-message">
        {errors.email}
      </div>
    </div>
    <div className="form-element">
      <label htmlFor="phoneNumber">Phone number:</label>
      <input
        className="input"
        type="tel"
        id="phoneNumber"
        name="phoneNumber"
        value={values.phoneNumber}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      <div className="error-message">
        {errors.phoneNumber}
      </div>
    </div>

    <div className="text-center">
      <button className="button" id="send" type="submit">Send</button>
    </div>
  </form>
);

Use the useControlledForm hook

Since React 16.8.0 you can use the new hooks.

This hook recives two parameters:

• The initial state of the form
• The validations of the form

And returns the state values and functions with the logic of manage the form.

Example:

import { useControlledForm } from 'with-controlled-form';

// Setup of the initial state of the component
const formState = {
  email: '',
  phoneNumber: '',
};

// Add validations easly!
const formValidations = {
  email: {
    isRequired: true,
    isMinLength: 3,
    isMaxLength: 30,
    isEmail: [true, 'email is not valid!'],
  },
  phoneNumber: {
    isRequired: true,
    isMinLength: 6,
    isMaxLength: 15,
  }
};

const FormWithUseControlledFormHook = ({ myHandleSubmit }) => {
  const {
    values,
    errors,
    handleChange,
    handleSubmit
   } = useControlledForm(formState, formValidations);

  return (
    <Form
      values={values}
      errors={errors}
      handleChange={handleChange}
      handleSubmit={() => handleSubmit(myHandleSubmit)}
    />
  )
}

And the Form component (is the same Form used on the HOC example):

const Form = ({
  values,
  errors,
  handleChange,
  handleBlur,
  handleSubmit
}) => (
  <form onSubmit={handleSubmit}>
    <div className="form-element">
      <label htmlFor="email">Email:</label>
      <input
        className="input"
        type="text"
        id="email"
        name="email"
        value={values.email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      <div className="error-message">
        {errors.email}
      </div>
    </div>
    <div className="form-element">
      <label htmlFor="phoneNumber">Phone number:</label>
      <input
        className="input"
        type="tel"
        id="phoneNumber"
        name="phoneNumber"
        value={values.phoneNumber}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      <div className="error-message">
        {errors.phoneNumber}
      </div>
    </div>

    <div className="text-center">
      <button className="button" id="send" type="submit">Send</button>
    </div>
  </form>
);

Arguments

WithFormControlled HOC

| Name | Type | Description | ------| ---- | -----------| | Form Component | React component | This is the UI form component | Initial state | Object | This is the initial state of the form | Form validations | Object | This is all the form validations that you can custom

useFormControlled hook

| Name | Type | Description | ------| ---- | -----------| | Initial state | Object | This is the initial state of the form | Form validations | Object | This is all the form validations that you can custom

Validators API

| Name | Params | Description | | ------| ----- | -----------| | isRequired | Boolean: verify, [optional] String: message | Check if value is truthy | | isEmail | Bolean: verify, [optional] String: message | Check if value match with /\S+@\S+\.\S+/ | | isMinLength | Int: size, [optional] String: message | Check if value has min length as string | | isMaxLength | Int: size, [optional] String: message | Check if value has max length as string | | isEqual | String: value, [optional] String: message | Check if value is equal with another string | | custom | Function: callback | Check the result of the callback with result |

Form props recived in UI component

| Name | Type | Description | ------| ---- | ----------- | | values | Object | This object contains the Form state values | errors | Object | This object contains an array of error messages for each state value | isFormClean | Boolean | This value return if the Form is clean or empty | handleChange | Function | This function update the state values on change event | cleanForm | Function | This function clean the form values, witch means reset the state | handleBlur | Function | This function update the error message if exists on blur the respective input

Example of Validators API

const values = {
  phoneNumber: '1234567890'
};

const validations = {
  phoneNumber: {
    isRequired: true,
    isMinLength: 6,
    isMaxLength: 15,
    custom (value) {
      console.log(value) // the value of phoneNumber
      const result = /^55/.test(value);
      const message = 'The phone number should start with 55';

      // you must return a object with result boolean value and message string value
      return { result, message };
    }
  },
  email: {
      // Using custom messages!
      isRequired: [true, 'The email is required!'],
      isMinLength: [6, 'The email must contain at least 6 chatacters']
  }
};

// pass to WithControlledForm HOC

Why with-controlled-form ?

The forms are basic elements in an app. Make a lot of forms in an app ends in repeated logic and code.

Using this library finally i can make my UI Forms without the trouble of how to manage the state, the logic of the validations and how to operate it.

Now you can do it too!