jotai-hook-form
is a way to build out complex forms with jotai, built off of JSON Pointers.
Inspired by react-hook-form
, it allows for the progressive building of a form data object, letting you add fields and manage the form data one field at a time.
jotai-hook-form
import { useSetAtom } from 'jotai'
import { createFormAtoms, useFieldAtom } from 'jotai-hook-form'
import type { FieldAtom } from 'jotai-hook-form'
type FormData = {
firstName: string;
lastName: string;
phoneNumber: number;
};
//1. Define your form data atom
const dataAtom = atom({} as FormData);
const { fieldAtom } = createFormAtoms<FormData>({ dataAtom });
//2. Initialise fields on your data atom
const firstNameFieldAtom = fieldAtom("/firstName")
const lastNameFieldAtom = fieldAtom("/lastName")
const phoneNumberFieldAtom = fieldAtom("/phoneNumber")
const submitAtom = atom(null, (set, get) => {
const data = get(dataAtom)
console.log("Form data:", { data })
})
const Form = () => {
const submit = useSetAtom(submitAtom)
return (
<form onSubmit={submit}>
<Field type="text" placeholder="First name" fieldAtom={firstNameFieldAtom} />
<Field type="text" placeholder="Last name" fieldAtom={lastNameFieldAtom} />
<Field type="number" placeholder="Phone number" fieldAtom={phoneNumberFieldAtom} />
<button type="submit">Submit</button>
</form>
);
};
const Field = ({ fieldAtom: FieldAtom, ...inputProps }) => {
const field = useFieldAtom(fieldAtom)
return <input {...inputProps} {...field}/>
}
jotai-hook-form
makes available to tools to built form logic both at the atom level as well as the hook level. Depending on how you build out the form at which level, there are different functions at your disposal to make it possible.
createFormAtoms
takes in a dataAtom
which will hold your form data object. It accepts the optional errorStackAtom
, which will be responsible for storing a mapping from a field's JSON Pointer, to an array of errors. There is also an optional third atom parameter for transientFieldsAtom
which will hold all values for your transient fields.
const dataAtom = atom<FormData>({})
const errorStackAtom = atom([] as ErrorStack)
const transientFieldsAtom = atom({})
const formAtoms = createFormAtoms<FormData>({
dataAtom,
errorStackAtom,
transientFieldsAtom
})
The createFormAtoms
function returns a list of atoms that can be used to build out forms and corresponding form logic:
fieldAtom
: Add a field to the form object, defaults to an uncontrolled fieldregisterAtom
: Add an uncontrolled field to the form objectcontrolAtom
: Add a controlled field to the form objecthiddenAtom
: Add a transient field to the transient fields objectwatchAtom
: Subscribe to an individual field (both form and transient)validationAtom
: Takes in a resolver that maps form data to errors and stores those errors in theerrorStackAtom
formActionsAtom
: A reducer atom. Currently supports resetting of the form state.setAtom
: Can be used to set a specific field (form or transient).
From here, you can now use fieldAtom
to specify all the fields within your form. These fields will be added as properties to the dataAtom
To gain control over form fields and logic within the hook level, pass in the returned object from createFormAtoms
into the hook useFormAtoms
.
The returned hooks handle the behaviour that would need to be manually coded if you were to only build out the form in the atom level, like listening to mounting/un-mounting, and pulling in the correct value and error for fields from your dataAtom
and errorStackAtom
respectively.
...
const formAtoms = createFormAtoms<FormData>({ dataAtom, errorStackAtom })
function useForm() {
const {
useField,
useControlledField,
useTransientField
} = useFormAtoms(formAtoms)
...
}
As seen, useFormAtoms
returns 3 hooks, each mapping to a one of each type of field:
useField
: uncontrolled fields (no explicit value prop)useControlledField
: controlled fields (explicitly set value prop)useTransientField
: transient fields (fields not storing in the data object).
Each hook takes in a JSON Pointer that will specify the property within the data object that will correspond to a field.
Controlled fields are the bread-and-butter for more complex forms with fields needing more advanced logic than what is available from vanilla form elements. These would include components like react-select
's Select
, or simply any form component that as input value
and onChange
as props.
Controlled fields can be created with fieldAtom
by default
Otherwise, controlled fields can be built using the useControlledField
hook, or using the controlAtom
- for the onChange
injection - in combination with the watchAtom
to get the value
. controlAtom
is returned by createFormAtoms
function, whereas useControlledField
comes from useFormAtoms
const lastNameFieldAtom = fieldAtom('/lastName')
is equivalent to
const lastName = useControlledField('/lastName')
or
const lastNameChangeAtom = set(controlAtom, '/lastName')
const lastNameValueAtom = watchAtom('/lastName')
Uncontrolled fields are either vanilla HTML form elements (input
, select
, etc.) or components whose ref is attached to a vanilla form element (usually through the use of forwardRef
). They have an internal, DOM-controlled value property that can be managed via refs, thereby not requiring re-renders to update their value within the element.
Uncontrolled fields are the optimal way to build forms as they can listen to input changes without needing a re-render to update the value in the view.
Uncontrolled fields can be handled by initialising a field with the useField
hook, or the registerAtom
that is returned by createFormAtoms
const firstNameAtom = fieldAtom('/firstName', { type: 'uncontrolled' })
is equivalent to
const firstName = useField('/firstName')
or
const firstNameAtom = set(registerAtom, '/firstName')
Transient fields: fieldAtom
, useTransientField
, hiddenAtom
"Transient" fields, as we've coined them, are fields that exist within the form's view and logic but shouldn't be stored on the form data object. This is useful for fields that conditionally render different sections of a form, where you only want to store the actual data fields and not whether the section is showing.
Transient fields are stored seperately to the data object. jotai-hook-form
will store these fields in the transientFieldsAtom
passed into createFormAtoms
. If this was not passed in, it will use an internal atom.
const formSection = fieldAtom('/currentSection', { type: 'transient' })
is equivalent to
const formSection = useTransientField('/currentSection')
or
const formSectionAtom = set(hiddenAtom, '/currentSection')
const formSectionValueAtom = watchAtom('/currentSection')
Whereas fields created with useField
, useControlledField
are stored within the dataAtom
's object, fields created with useTransientField
are stored either in an internal store specific to transient fields, or in the optional transientStoreAtom
parameter of createFormAtoms
.
Note: useTransientField
acts exactly like useControlledField
and does not try to be smart about the DOM element it is attached to, and must be controlled explicitly.
In the case that fields need to be removed and re-added to the form data object whenever they leave or re-enter the DOM respectively (i.e. conditional fields), the <Conditional>
component can wrap around the element within the view to listen to these changes.
<Conditional>
takes in 4 props:
show: boolean
: A flag to conditionally render its children.fields?: { listeners: Listeners }
: An array of field objects corresponding to the fields inside theConditional
componentonMount: () => void
: A function to run on-mount.onUnmount: () => void
: A function to run on-unmount.
To connect a field that has already been initialised by one of the 3 hooks returned by useFormAtoms
, you can spread the listeners
property of the field on <Conditional>
. This listeners
property contains both onMount
and onUnmount
functions that will handle removing/re-adding the field to the form data object on event trigger.
Example:
...
const conditionalFieldOne = useField('/conditionalFieldOne')
const conditionalFieldTwo = useField('/conditionalFieldTwo')
const showConditional = useTransientField('/showConditional')
return (
<form>
<input
type="checkbox"
checked={showConditional.value}
onClick={e => showConditional.onChange(!e.target.checked)}
/>
<Conditional
show={showConditional.value}
fields={[conditionalFieldOne, conditionalFieldTwo]}
>
<input type="text" {...conditionalFieldOne} />
<input type="text" {...conditionalFieldTwo} />
</Conditional>
</form>
)
...
Opposed to other libraries, like react-hook-form
, <Conditional>
works with both controlled and uncontrolled fields.
Field level validation can be specified using the validate
property within the optional config for fieldAtom
, useField
, or useControlledField
.
An error object must be returned from the validate
function. Error objects have type: string
, and message?: string
properties.
Example
const validatedFieldAtom = fieldAtom('/validated', {
validate: (field: { value: any, touched: boolean, dirty: boolean }) => {
if (field.value === "" && field.touched) {
return {
type: "required",
message: "This field is required"
}
}
}
})
High-level API | Description |
---|---|
createFormAtoms() |
A function to initialise a jotai-hook-form form. Takes in a dataAtom and optionally errorStackAtom , and transientFieldsAtom |
useFormAtoms() |
A hook to utilise the form atoms returned by createFormAtoms |
useFieldAtom() |
A hook that converts a field atom created by fieldAtom into an object representation |
Atoms returned from createFormAtoms
Form atoms | Description |
---|---|
fieldAtom() |
An atom that specifies fields within the form's dataAtom , using JSON Pointers |
registerAtom() |
An atom that creates an uncontrolled field within the form's dataAtom , using JSON Pointers |
controlAtom() |
An atom that creates a controlled field within the form's dataAtom , using JSON Pointers |
hiddenAtom() |
An atom that creates a transient field within the form's transientFieldsAtom , using JSON Pointers |
watchAtom() |
An atom that listens to a property within the form's dataAtom |
errorAtom() |
An atom that listens to a field's error within the form's errorStackAtom |
errorStackAtom() |
An atom that stores form errors by JSON Pointer and error type |
Properties of a field when returned from useFieldAtom
Properties | Description |
---|---|
name |
The JSON Pointer of the field |
value |
The current value of the field |
onChange |
The function to run when the field input value changes (not on uncontrolled fields) |
onBlur |
The function to run when the field input is blurred |
listeners |
Contains onMount , and onUnmount functions to pass into the <Conditional> component |
status |
Contains dirty , and touched statuses for the field |
error |
The current error value of the field |
Component | Description |
---|---|
Conditional |
Component that handles conditional form fields, removing them from the form dataAtom on unmount, and listening to onmount |