reacty-form v0.1.2

Reacty-form

Reacty-form is a React form management library that provides a set of hooks and components (very similar to react-hook-form) to manage form state efficiently. It leverages the power of Legend-State for state management, offering fine-grained reactivity and performance optimizations.

Installation

npm install reacty-form
# or
yarn add reacty-form
# or
pnpm add reacty-form

Getting Started

Here's a basic example of using Reacty-form in a React application:

import React from 'react';
import { Controller, useForm } from 'reacty-form';

function App() {
    const { register, formState: { errors } } = useForm();

    const onSubmit = (data) => {
        console.log(data);
    };

    return (
        <form onSubmit={form.handleSubmit(onSubmit)}>
            <input {...register('name')} />
            {errors.name && <p>Name is required.</p>}
            <input type="submit" />
        </form>
    );
}

export default App;

API Reference

useForm

useForm is a custom hook for managing forms with ease. It takes one object as an optional argument. The following example demonstrates all of its properties along with their default values.

Generic props:

Schema validation props:

Props:

• mode: onChange | onBlur | onSubmit | onTouched | all = 'onSubmit'

  This option allows you to configure the validation strategy before a user submits the form. The validation occurs during the onSubmit event, which is triggered by invoking the handleSubmit function.

  Name	Type	Description
  onSubmit	string	Validation is triggered on the submit event, and inputs attach onChange event listeners to re-validate themselves.
  onBlur	string	Validation is triggered on the blur event.
  onChange	string	Validation is triggered on the changeevent for each input, leading to multiple re-renders. Warning: this often comes with a significant impact on performance.
  onTouched	string	Validation is initially triggered on the first blur event. After that, it is triggered on every change event. Note: when using with Controller, make sure to wire up onBlur with the render prop.
  all	string	Validation is triggered on both blur and change events.

• reValidateMode: onChange | onBlur | onSubmit = 'onChange'

  This option allows you to configure validation strategy when inputs with errors get re-validated after a user submits the form (onSubmit event and handleSubmit function executed). By default, re-validation occurs during the input change event.

• defaultValues: FieldValues | Promise<FieldValues>

  The defaultValues prop populates the entire form with default values. It supports both synchronous and asynchronous assignment of default values. While you can set an input's default value using defaultValue or defaultChecked (as detailed in the official React documentation), it is recommended to use defaultValues for the entire form.

  // set default value sync
  useForm({
      defaultValues: {
          firstName: '',
          lastName: ''
      }
  })
  
  // set default value async
  useForm({
      defaultValues: async () => fetch('/api-endpoint');
  })

  Rules

  • You should avoid providing undefined as a default value, as it conflicts with the default state of a controlled component.
  • defaultValues are cached. To reset them, use the reset API.
  • defaultValues will be included in the submission result by default.
  • It's recommended to avoid using custom objects containing prototype methods, such as Moment or Luxon, as defaultValues.
  • There are other options for including form data:

    // include hidden input
    <input {...register("hidden")} type="hidden" />
    register("hidden", { value: "data" })
    
    // include data onSubmit
    const onSubmit = (data) => {
        const output = {
            ...data,
            others: "others"
        }
    }

• values: FieldValues

  The values props will react to changes and update the form values, which is useful when your form needs to be updated by external state or server data.

  // set default value sync
  function App({ values }) {
      useForm({
          values  // will get updated when values props updates       
      })
  }
  
  function App() {
      const values = useFetch('/api');
      
      useForm({
          defaultValues: {
              firstName: '',
              lastName: '',
          },
          values, // will get updated once values returns
      })
  }

• resetOptions: KeepStateOptions

  This property is related to value update behaviors. When values or defaultValues are updated, the reset API is invoked internally. It's important to specify the desired behavior after values or defaultValues are asynchronously updated. The configuration option itself is a reference to the reset method's options.

  // by default asynchronously value or defaultValues update will reset the form values
  useForm({ values })
  useForm({ defaultValues: async () => await fetch() })
  
  // options to config the behaviour
  // eg: I want to keep user interacted/dirty value and not remove any user errors
  useForm({
      values,
      resetOptions: {
          keepDirtyValues: true, // user-interacted input will be retained
          keepErrors: true, // input errors will be retained with value update
      }
  })

• criteriaMode: firstError | all

  | • When set to firstError (default), only the first error from each field will be gathered. • When set to all, all errors from each field will be gathered. | --- | | --- | --- |

• shouldFocusError: boolean = true

  When set to true (default), and the user submits a form that fails validation, focus is set on the first field with an error.

  Note: only registered fields with a ref will work. Custom registered inputs do not apply. For example: register('test') // doesn't work

  Note: the focus order is based on the register order.

  ---

• delayError: number

  This configuration delays the display of error states to the end-user by a specified number of milliseconds. If the user corrects the error input, the error is removed instantly, and the delay is not applied.

• resolver: Resolver

  This function allows you to use any external validation library such as Yup, Zod, Joi, Vest, Ajv and many others. The goal is to make sure you can seamlessly integrate whichever validation library you prefer. If you're not using a library, you can always write your own logic to validate your forms.

  npm install @hookform/resolvers

### **Props**

| Name | Type | Description |
| --- | --- | --- |
| `values` | `object` | This object contains the entire form values. |
| `context` | `object` | This is the `context` object which you can provide to the `useForm` config. It is a mutable `object` that can be changed on each re-render. |
| `options` | `{   criteriaMode: string, fields: object, names: string[] }` | This is the option object containing information about the validated fields, names and `criteriaMode` from `useForm`. |

### **Rules**

- Schema validation focuses on field-level error reporting. Parent-level error checking is limited to the direct parent level, which is applicable for components such as group checkboxes.
- This function will be cached.
- Re-validation of an input will only occur one field at time during a user’s interaction. The lib itself will evaluate the `error` object to trigger a re-render accordingly.
- A resolver can not be used with the built-in validators (e.g.: required, min, etc.)
- When building a custom resolver:
    - Make sure that you return an object with both `values` and `errors` properties. Their default values should be an empty object. For example: `{}`.
    - The keys of the `error` object should match the `name` values of your fields.

### **Examples**

```jsx
import React from 'react';
import { useForm } from 'reacty-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from "yup";

const schema = yup.object().shape({
    name: yup.string().required(),
    age: yup.number().required(),
}).required();

const App = () => {
    const { register, handleSubmit } = useForm({
        resolver: yupResolver(schema),
    });

    return (
        <form onSubmit={handleSubmit(d => console.log(d))}>
        <input {...register("name")} />
        <input type="number" {...register("age")} />
        <input type="submit" />
        </form>
    );
};
```

Return

The following list contains reference to useForm return props.

• register
• formState
• handleSubmit
• reset
• resetField
• setError
• clearErrors
• setValue
• setFocus
• getValues
• getFieldState
• trigger
• control

useController

This custom hook powers the Controller. It's useful for creating reusable Controlled input.

Props

The following table contains information about the arguments for useController.

The following table contains information about properties which useController produces.

Example

import { TextField } from "@material-ui/core";
import { useController, useForm } from "reacty-form";

function Input({ form, name }) {
  const {
    field,
    fieldState: { invalid, isTouched, isDirty },
    formState: { touchedFields, dirtyFields }
  } = useController({
    name,
    form,
    rules: { required: true },
  });

  return (
    <TextField 
      onChange={field.onChange} // send value to hook form 
      onBlur={field.onBlur} // notify when input is touched/blur
      value={field.value} // input value
      name={field.name} // send down the input name
      inputRef={field.ref} // send input ref, so we can focus on input when error appear
    />
  );
}

Tips

• It's important to be aware of each prop's responsibility when working with external controlled components, such as MUI, AntD, Chakra UI. Its job is to spy on the input, report, and set its value.
  • onChange: send data back to hook form
  • onBlur: report input has been interacted (focus and blur)
  • value: set up input initial and updated value
  • ref: allow input to be focused with error

  • name: give input an unique name

    It's fine to host your state and combined with useController.

    const { field } = useController();
    const [value, setValue] = useState(field.value);
    
    onChange={(event) => {
      field.onChange(parseInt(event.target.value)) // data send back to hook form
      setValue(event.target.value) // UI state
    }}

• Do not register input again. This custom hook is designed to take care of the registration process.

  const { field } = useController({ name: 'test' })
  
  <input {...field} /> // ✅
  <input {...field} {...register('test')} /> // ❌ double up the registration

• It's ideal to use a single useController per component. If you need to use more than one, make sure you rename the prop. May want to consider using Controller instead.

  const { field: input } = useController({ name: 'test' })
  const { field: checkbox } = useController({ name: 'test1' })
  
  <input {...input} />
  <input {...checkbox} />

Controller

Reacty-form embraces uncontrolled components and native inputs, however it's hard to avoid working with external controlled component such as React-Select, AntD and MUI. This wrapper component will make it easier for you to work with them.

Props

The following table contains information about the arguments for Controller.

Example

import ReactDatePicker from "react-datepicker"
import { TextField } from "@material-ui/core"
import { useForm, Controller } from "reacty-form"

type FormValues = {
  ReactDatepicker: string
}

function App() {
  const form = useForm<FormValues>()

  return (
    <form onSubmit={form.handleSubmit((data) => console.log(data))}>
      <Controller
        form={form}
        name="ReactDatepicker"
        render={({ field: { onChange, onBlur, value, ref } }) => (
          <ReactDatePicker
            onChange={onChange} // send value to hook form
            onBlur={onBlur} // notify when input is touched/blur
            selected={value}
          />
        )}
      />

      <input type="submit" />
    </form>
  )
}

useFormContext

This custom hook allows you to access the form context. useFormContext is intended to be used in deeply nested structures, where it would become inconvenient to pass the context as a prop.

Return

This hook will return all the useForm return methods and props.

const methods = useForm()

<FormProvider {...methods} /> // all the useForm return props

const methods = useFormContext() // retrieve those props

RULES

You need to wrap your form with the FormProvider component for useFormContext to work properly.

Example

import React from "react"
import { useForm, FormProvider, useFormContext } from "reacty-form"

export default function App() {
  const form = useForm()
  const onSubmit = (data) => console.log(data)
  const { register, reset } = form

  useEffect(() => {
    reset({
      name: "data",
    })
  }, [reset]) // ❌ never put `methods` as the deps

  return (
    <FormProvider form={form}>
      {/* pass all methods into the context */}
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <NestedInput />
        <input {...register("name")} />
        <input type="submit" />
      </form>
    </FormProvider>
  )
}

function NestedInput() {
  const { register } = useFormContext() // retrieve all hook methods
  return <input {...register("test")} />
}

FormProvider

This component will host context object and allow consuming component to subscribe to context and use useForm props and methods.

Props

This following table applied to FormProvider, useFormContext accepts no argument.

Example

import React from "react"

import { useForm, FormProvider, useFormContext } from "reacty-form"

export default function App() {
  const form = useForm()

  const onSubmit = (data) => console.log(data)
  const { register, reset } = form

  useEffect(() => {
    reset({
      name: "data",
    })
  }, [reset]) // ❌ never put `methods` as the deps

  return (
    <FormProvider form={form}>
      {/* pass all methods into the context */}
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <NestedInput />
        <input {...register("name")} />
        <input type="submit" />
      </form>
    </FormProvider>
  )
}

function NestedInput() {
  const { register } = useFormContext() // retrieve all hook methods

  return <input {...register("test")} />
}

useWatch

It allows you to subscribe to any changes that happen in a particular form field.

Props (the first parameter of the useWatch hook)

Callback (the second parameter of the useWatch hook)

callback: (e: ObserveEventCallback<TFieldValues>) => void

• This callback is where you write the logic for handling changes to the form field's value.
• ObserveEventCallback comes from legend-state. This hook internally uses useObserve hook of legend state to subscribe for state changes.

useFormState

This custom hook returns the current state of the form.

Props

Return

Example

import * as React from "react";
import { useForm, useFormState } from "reacty-form";

function Child({ form }) {
  const { dirtyFields } = useFormState({
    form
  });

  return dirtyFields.firstName ? <p>Field is dirty.</p> : null;
};

export default function App() {
  const form = useForm({
    defaultValues: {
      firstName: "firstName"
    }
  });
  const { register, handleSubmit } = form;
  const onSubmit = (data) => console.log(data);

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} placeholder="First Name" />
      <Child form={form} />

      <input type="submit" />
    </form>
  );
}

useFieldArray

Custom hook for working with Field Arrays (dynamic form). The motivation is to provide better user experience and performance.

Props

Example

function FieldArray() {
  const form = useForm();
  const { fields, append, prepend, remove, swap, move, insert } = useFieldArray({
    form, // form props comes from useForm (optional: if you are using FormProvider)
    name: "test", // unique name for your Field Array
  });

  return (
    {fields.map((field, index) => (
      <input
        key={index}
        {...form.register(`test.${index}.value`)} 
      />
    ))}
  );
}

Return

Mentions

• I want to mention legend state for such a beautiful library which handles state management beautifully
• I also want to mention react-hook-form from which I took so much inspiration while building this library.

Support

If you enjoy using this project or want to help improve it, your support means the world! You can:

• ⭐ Star the repository
• 🗨️ Share feedback

License

This project is licensed under the MIT License.