@matthew.ngo/reform

# Reform Form Management Reform provides a comprehensive form management system that helps you create, manage, and validate complex forms with multiple groups. This document covers the form management capabilities of Reform. ## Table of Contents - [Overview](#overview) - [Form Groups](#form-groups) - [Field Management](#field-management) - [Form State](#form-state) - [Form Reset](#form-reset) - [Form Controller](#form-controller) - [API Reference](#api-reference) ## Overview Reform's form management system is built around the concept of form groups, which allow you to organize related data together. The core functionality includes: 1. **Form Groups**: Create, update, and manage collections of related data 2. **Field Management**: Register and control form fields with type safety 3. **Form State**: Track and manage form state (dirty, touched, valid, etc.) 4. **Form Reset**: Reset the entire form or specific groups 5. **Form Controller**: Controlled components integration ## Form Groups Form groups are the fundamental building blocks of Reform forms. Each group contains related data and has a unique identifier. ### Basic Usage ```tsx import { useReform } from '@reform/core'; type UserForm = { name: string; email: string; }; const MyForm = () => { const form = useReform<UserForm>({ defaultData: { name: '', email: '' }, minGroups: 1, maxGroups: 5, }); // Add a new group const handleAddGroup = () => { form.addGroup(); }; // Remove a group const handleRemoveGroup = (index: number) => { form.removeGroup(index); }; return ( <div> {form.getGroups().map((group, index) => ( <div key={group.id}> <input {...form.register(index, 'name')} placeholder="Name" /> <input {...form.register(index, 'email')} placeholder="Email" /> <button onClick={() => handleRemoveGroup(index)}>Remove</button> </div> ))} <button onClick={handleAddGroup}>Add Group</button> </div> ); }; ``` ### Batch Operations Reform supports batch operations for efficiently managing multiple groups: ```tsx // Update multiple groups at once form.batchUpdate([0, 2, 4], (data) => ({ status: 'active', lastUpdated: new Date(), })); // Remove multiple groups form.batchRemove([1, 3]); ``` ## Field Management Reform provides type-safe field registration and management: ```tsx // Register a field with React Hook Form <input {...form.register(0, 'email')} /> // Set a field value programmatically form.setValue(0, 'email', 'user@example.com'); // Get a field value const email = form.getFieldValue(0, 'email'); ``` ## Form State Track and manage form state: ```tsx // Check if a field is dirty const isDirty = form.fieldState.isDirty(0, 'email'); // Check if a field is touched const isTouched = form.fieldState.isTouched(0, 'email'); // Get complete field state const fieldState = form.fieldState.get(0, 'email'); // Check form-wide state const isFormDirty = form.formState.isDirty; const isFormValid = form.formState.isValid; const isSubmitting = form.formState.isSubmitting; ``` ## Form Reset Reset the form to its initial state or to specific values: ```tsx // Reset the entire form to initial values form.resetForm(); // Reset with new default values form.resetForm({ groups: [ { id: 'new-id-1', data: { name: 'New Name', email: 'new@example.com' }, }, ], }); // Reset but keep dirty state form.resetForm(undefined, { keepDirty: true }); // Reset to a clean state with specific number of groups form.resetToCleanState(3); // Reset a specific group form.resetGroup(0); ``` ## Form Controller For more complex form controls, use the `ReformController` component: ```tsx import { ReformController } from '@reform/core'; const MyForm = () => { const form = useReform<UserForm>(config); return ( <div> <ReformController index={0} field="email" control={form.formMethods.control} rules={{ required: 'Email is required' }} render={({ field, fieldState }) => ( <div> <input {...field} placeholder="Email" className={fieldState.error ? 'error' : ''} /> {fieldState.error && <p>{fieldState.error.message}</p>} </div> )} /> </div> ); }; ``` ## API Reference ### useReform ```typescript function useReform<T extends Record<string, any>>( config: DynamicFormConfig<T> ): ReformReturn<T> ``` #### Configuration Options | Option | Type | Default | Description | | ----------- | --------------------------------------- | ----------- | ------------------------------------- | | value | `FormGroup<T>[]` | `[]` | Initial form groups | | minGroups | `number` | `1` | Minimum number of groups | | maxGroups | `number` | `Infinity` | Maximum number of groups | | defaultData | `T` | `{}` | Default data for new groups | | onChange | `(groups: FormGroup<T>[]) => void` | `undefined` | Callback when form changes | | schema | `ObjectSchema<T>` | `undefined` | Yup schema for validation | | labels | `Record<string, string>` | `{}` | Field labels for error messages | ### Form Group Management | Method | Description | | ------------- | --------------------------------------------- | | getGroups | Get all form groups | | setGroups | Set all form groups | | addGroup | Add a new group | | removeGroup | Remove a group at the specified index | | moveGroup | Move a group from one index to another | | duplicateGroup| Create a copy of an existing group | | batchUpdate | Update multiple groups at once | | batchRemove | Remove multiple groups at once | ### Field Management | Method | Description | | ------------ | --------------------------------------------- | | register | Register a field with React Hook Form | | setValue | Set a field value | | getFieldValue| Get a field value | ### Form State | Property/Method | Description | | --------------- | --------------------------------------------- | | fieldState | Object with methods to check field state | | formState | Object with form-wide state properties | ### Form Reset | Method | Description | | ---------------- | --------------------------------------------- | | resetForm | Reset the form to initial or provided values | | resetToCleanState| Reset to a clean state with n groups | | resetGroup | Reset a specific group to default values | ### ReformController ```typescript function ReformController<TFieldValues>({ index, field, control, render, rules, defaultValue, shouldUnregister, }: ReformControllerProps<TFieldValues>): JSX.Element ``` #### Props | Prop | Type | Description | | --------------- | ---------------------------------------------------- | ------------------------------------- | | index | `number` | Group index | | field | `string` | Field name | | control | `Control<TFieldValues>` | Form control from useForm | | render | `(props: { field, fieldState, formState }) => JSX.Element` | Render function for the field | | rules | `object` | Validation rules | | defaultValue | `any` | Default value for the field | | shouldUnregister| `boolean` | Whether to unregister on unmount | ### FormGroup Type ```typescript interface FormGroup<T = any> { id: string; data: T; } ```