@xtreamsrl/react-forms

This package exposes a FormProvider and the following hooks: useForm, useFormContext, useController.
It is useful to ease form management.

Installation

``shell
npm install @xtreamsrl/react-forms
`

Usage

In order to use this library properly it is advantageous to follow the description of the single hooks.
They are listed in an order that allows to add each required piece step by step.

$3

First thing first, it is necessary to rely on the useForm hook to have access to methods and properties to manage and control forms.
This hook is used to encapsulate the logic and state related to form management.

The useForm hook accepts an object containing two fields:
1. initialValues to populate the entire form with default values.
2. validationSchema to integrate yup inputs' validation.

>! Caution: At the moment only yup is accepted as validator, despite react-hook-form supports Yup, Zod, Joi, Vest, Ajv and many others.

`tsx
import {useForm} from "@xtreamsrl/react-forms"
import * as yup from "yup"

const validationSchema = yup.object().shape({
email: yup.string().email().required("Required"),
password: yup.string().min(5, "Password is too short").required("Required"),
});
`

See yup on GitHub to know more about validation.

`tsx
const form = useForm({initialValues: {email: "", password: ""}, validationSchema});
`

The useForm return value has three fields:
- formProps contains methods to handle the form. The following two fields are subfields of this object.
- formState is an object that contains information about the entire form state. It helps to keep on track with the user's interaction with the form application.
- reset allows to reset the entire form state, fields reference, and subscriptions. It also allows partial reset through optional parameters.

$3

Once form management methods are available, it is possible to define a form that will be wrapped using a provider.

When wrapping the form, it can be helpful to specify the object type to be handled.
In other terms, it can be specified the TypeScript type of the fields that make up the entire form.
For example, LoginData has been defined from the validation schema: type LoginData = yup.InferType and specified to the Provider.

Then, it requires formProps, containing all the methods returned by the useForm hook.

`tsx
import {FormProvider} from "@xtreamsrl/react-forms"
`

`tsx
{...form.formProps}>


{
event?.preventDefault();
login(values.email, values.password)
})}>


Login




`
> See the useController blow to see an example of how to define the Input component visible in this snippet.

$3

This hook is used to bind a single input field to the form, it powers the Controller. It provides a way to manually control an input field while still integrating with the overall form state.
The Controller component is a wrapper around the input component that works with the useController hook.

The hook accepts an object containing:
- name: unique name of the input, it is the only required field.
- control: control object provided by invoking useForm. Optional when using FormProvider.
- rules.
- shouldUnregister: value that indicate that the Input will be unregistered after unmount and defaultValues will be removed as well.
- defaultValue: it cannot be undefined.

`tsx
import {useController} from "@xtreamsrl/react-forms"

export function Input({name, type, placeholder}: {
name: string, type: string, placeholder: string
}) {
const {
field: {
ref,
value,
...inputProps
},
fieldState: {
error,
invalid
}
} = useController({name});

return



}
`
The useController return values (field, fieldState and formState) can be explored in the dedicated page of the react-hook-form documentation, given that this hook return values have not been manipulated before being returned.

$3

This custom hook allows 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.
It returns setError, watch, formState.
Remember that it is necessary to wrap the form with the FormProvider component for useFormContext to work properly.
`tsx
import { useForm, FormProvider, useFormContext } from "@xtreamsrl/react-forms"

export default function App() {
const {formProps: methods} = useForm()
const onSubmit = (data) => console.log(data)

return (

// pass all methods into the context

{/.../}




)
}

function NestedInput({name: string}) {
const {setError, watch, formState} = useFormContext()

const value = watch(name);
const companyName = watch('companyName');
const companyAddress = watch('companyAddress');

const invalid = name in formState.errors;

// ...
}
`
The watch method watches specified inputs and return their values.
It is useful to render input value and for determining what to render by condition. See more on the documentation page.

The setError` function allows you to manually set one or more errors. See more about setError.

Who we are

A proudly 🇮🇹 software development and data science startup.
We consider ourselves a family of talented and passionate people building their own products and powerful solutions for our clients. Get to know us more on xtreamers.io or follow us on LinkedIn.