This package exposes a FormProvider and the following hooks: useForm, useFormContext, useController. It is useful to ease form management.
npm install @xtreamsrl/react-formsThis package exposes a FormProvider and the following hooks: useForm, useFormContext, useController.
It is useful to ease form management.
``shell`
npm install @xtreamsrl/react-forms
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}>
`
> 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
{error?.message?.toString()}
}
`
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.