@andydowell/use-form-state v2.0.5

FormState React Hook

The useFormState hook is a utility for managing form state in React applications. It provides functionality for tracking and validating form fields, as well as extracting form data in different formats. With useFormState, you can easily handle form interactions and ensure data integrity.

Installation

To install the use-form-state package, run the following command:

npm install @andydowell/use-form-state

Usage

Initializing the Form State

import { useFormState } from "@andydowell/use-form-state";

const formState = useFormState(formFieldParams, options);

Before using the hook, you need to define the formFieldParams. These props represent the structure of your form and include information such as default values, validation rules, and error messages.

Each field in the formFieldParams is defined by a key-value pair, where the key is the name of the field and the value is an object with the following properties:

The second parameter options is an object with the following properties:

You can see an example of formFieldParams and options in the Example section.

API

The useFormState hook returns an object with the following properties and methods:

const { state, set, update, checkIfAllValid, extractStateValue, reset } = useFormState(formFieldParams, options);

The state object contains the current values and validation status of each form field. The set function allows you to update single form field value. The update function allows you to update multiple form field values. The checkIfAllValid function checks if all fields are valid. The extractStateValue function extracts the form data in the specified format. The reset function resets the form to its initial state.

Form State

Each form field in the state object is represented by an object with the following properties:

error is not updated immediately when the value of a form field changes. Instead, it is updated after a delay (default is 0.5 seconds) to prevent the error message from flashing when the user is typing. If the field is not interacted with, the error will not be updated. Running checkIfAllValid({ updateErrorType: true }) will update all errors immediately.

Updating Single Form Field Value

To update a form field value, use the set function:

set(key, value, setInteracted);

You can see an example of set in the Example section.

Updating Multiple Form Field Values

To update multiple form field values at once, use the update function:

update(data, setInteracted);

You can see an example of update in the Example section.

Checking Form Field Validity

You can check the validity of individual form fields by accessing the isValid property in the state object:

const isEmailValid = state.email.isValid;

Checking Overall Form Validity

To check if the entire form is valid, use the checkIfAllValid function:

const isFormValid = checkIfAllValid(options);

The options parameter is an object with the following properties:

The validation will check all form fields based on their defined rules and update their validation status and error messages accordingly. You can see an example of checkIfAllValid in the Example section.

Extracting Form Data

You can extract the form data in different formats using the extractStateValue function. Currently, two formats are supported: 'object' and 'formdata'.

Example: To extract the form data as an object:

const dataObject = extractStateValue({ format: "object" });

To extract the form data as FormData:

const formData = extractStateValue({ format: "formdata" });

You can see an example of extractStateValue in the Example section.

Resetting the Form

To reset the form to its initial state, use the reset function:

reset();

This will clear all form field values and reset their validation status. You can see an example of reset in the Example section.

Example

const newUser = useFormState({
  email: {
    defaultValue: "@",
    helperText: "Your Email Address",
    required: { message: "Please enter your email address" },
    validation: {
      longerThanOneChar: {
        validator: value => value.length > 1,
        message: "Email address must be longer than 1 character",
      },
      ["has-add-sign"]: {
        validator: value => value.includes("@"),
        message: "Email address must contain '@'",
      },
    },
  },
  password: {
    defaultValue: "",
    helperText: "Your Password",
    required: { message: "Please enter your password" },
    validation: {
      longerThanOneChar: {
        validator: value => value.length > 1,
        message: "Password must be longer than 1 character",
      },
    },
  },
  confirmPassword: {
    defaultValue: "",
    helperText: "Confirm Your Password",
    required: { message: "Please enter your password again" },
    validation: {
      longerThanOneChar: {
        validator: value => value.length > 1,
        message: "Password must be longer than 1 character",
      },
      matchPassword: {
        validator: (value, state) => value === state.password.value,
        message: "Passwords do not match",
      },
    },
  },
});

// ---------------------------------

const onSubmit = async e => {
  e.preventDefault();
  if (!newUser.checkIfAllValid()) return;

  const formdata = newUser.extractStateValue({ format: "formdata" });
  // ... Submit formdata to server
};

// ---------------------------------

const { email, password, confirmPassword } = newUser.state;

<form onSubmit={onSubmit}>
  <div>
    <Input value={email.value} onChange={e => newUser.update({ email: e.target.value })} />
    <p>{email.error?.message || email.helperText}</p>
  </div>
  <div>
    <Input type="password" value={password.value} onChange={e => newUser.set("password", e.target.value)} />
    <p>{password.error?.message || password.helperText}</p>
  </div>
  <div>
    <Input
      type="password"
      value={confirmPassword.value}
      onChange={e => newUser.set("confirmPassword", e.target.value)}
    />
    <p>{confirmPassword.error?.message || confirmPassword.helperText}</p>
  </div>
  <button type="submit">Submit</button>
  <button type="reset" onClick={newUser.reset}>
    Reset
  </button>
</form>;

License

This package is open source and available under the MIT License.