@principlestudios/react-jotai-forms

A flexible TypeScript-friendly forms library using React and Jotai

Additional dependencies currently include:

• zod
• react-i18next (recommended)

Why another forms library?

Forms on the web are deceptively difficult. Developers need to balance usability, accessibility, validation, APIs, and even custom fields, making each form a unique challenge, even within a single web application. Existing form libraries for React help significantly, but are laden with years of difficult API decisions.

Some of the primary goals of this library include:

• Support sub-forms. For instance, a check-out of a shopping cart may have two different address fields; we want a TypeScript-friendly AddressField component to be able to be created.
• Translatable validation. Form validation is tricky enough without the challenge of changing error messages within the validation schema; we want to provide developer-readable error codes for each field to be translated just before displaying to the end user.
• Support both uncontrolled and controlled components. Jotai provides an excellent library for storing state that does not force React re-renders; this allows our forms to both be correct and efficient.
• Mapping from API structure to form structure. Even when the APIs are designed with front-end developers in mind, there are many situations where the React component needs a different structure (especially for reuse).

Basic example

const myFormSchema = z.object({ name: z.string() });

type FormDemoProps = {
	onSubmit: (data: MyForm) => void;
};

export function FormDemo({ onSubmit }: FormDemoProps) {
	const form = useForm({
		schema: myFormSchema,
		defaultValue,
		fields: {
			name: ['name'],
		},
	});

	return (
		<form className="w-full h-full" onSubmit={form.handleSubmit(onSubmit)}>
			<JotaiInput {...form.fields.name.htmlProps()} />
			<button type="submit">{t('submit')}</button>
		</form>
	);
}

What won't this do?

To set some boundaries, there's a number of things this library will not support:

• Form presentation. Every application is unique; styled components will not be provided.
• Form layout. Because this library receives definitions for final object structures rather than user-driven structures, form layout cannot be determined.
• User-presentable error messages. This library will provide developer-readable error codes that can run through a translation library for user presentation.