Forms Hooks
Package Reference: This documentation covers the Forms hooks built on top of the @mapples/form package. For complete API documentation, see the @mapples/form package reference.
This guide covers all the available hooks in the Forms system and how to use them effectively in your React Native applications.
Core Hooks
useFormField
Hook for managing individual form fields with validation and state.
Function Reference: useFormField - Complete API documentation for the useFormField hook.
useFormField provides field-specific state, validation, and event handlers:
import { Form, useFormField } from '@mapples/form';
const EmailForm = () => {
return (
<Form onSubmit={(data) => console.log('Email form:', data)}>
<EmailField />
</Form>
);
};
const EmailField = () => {
const {
value,
error,
errors,
isTouched,
setValue,
touch,
validate
} = useFormField('email', '');
return (
<View>
<TextInput
value={value || ''}
onChangeText={setValue}
onBlur={() => touch('email')}
placeholder="Email"
keyboardType="email-address"
autoCapitalize="none"
/>
{isTouched && error && <Text style={{ color: 'red' }}>{error}</Text>}
</View>
);
};
useFormField Parameters
fieldPath: string- Dot notation path to the field (e.g., 'user.name')fallbackValue?: T- Default value to use if field is undefinedsubscribe?: boolean- Whether to subscribe to real-time value changes (default: true)
useFormField Returns
interface UseFormFieldReturns {
value: T | undefined;
error: string | undefined;
errors: ValidationError[] | undefined;
isTouched: boolean;
validate: () => void;
touch: (fieldName: string) => void;
setValue: (newValue: T) => void;
}
Additional Hooks
useFormArrayField
Hook for managing array fields with specialized array manipulation methods.
Function Reference: useFormArrayField - Complete API documentation for the useFormArrayField hook.
useFormArrayField provides functionality for dynamic form fields and array management:
import { useFormArrayField } from '@mapples/form';
const TagsForm = () => {
const { value, api } = useFormArrayField('tags', []);
const addTag = () => {
api.push('New Tag');
};
const removeTag = (index: number) => {
api.remove(index);
};
return (
<View>
{value?.map((tag, index) => (
<View key={index}>
<Text>{tag}</Text>
<Button
title="Remove"
onPress={() => removeTag(index)}
/>
</View>
))}
<Button title="Add Tag" onPress={addTag} />
<Button title="Remove First" onPress={() => api.dropLeft(1)} />
<Button title="Remove Last" onPress={() => api.dropRight(1)} />
</View>
);
};
useFormFieldToggle
Hook for managing toggle/boolean form fields.
Function Reference: useFormFieldToggle - Complete API documentation for the useFormFieldToggle hook.
useFormFieldToggle provides functionality for boolean/toggle form fields:
import { useFormFieldToggle } from '@mapples/form';
const ToggleField = () => {
const { value, toggle } = useFormFieldToggle('acceptTerms', false);
return (
<View>
<Switch value={value} onValueChange={toggle} />
<Text>Accept Terms: {value ? 'Yes' : 'No'}</Text>
</View>
);
};
useBindFormField
Hook for binding form fields with external components.
Function Reference: useBindFormField - Complete API documentation for the useBindFormField hook.
useBindFormField provides field binding functionality:
import { useBindFormField } from '@mapples/form';
const BoundField = () => {
const fieldProps = useBindFormField('username');
return (
<TextInput
{...fieldProps}
placeholder="Username"
/>
);
};
Context Hooks
useFormContext
Hook for accessing form context containing form state and methods.
Function Reference: useFormContext - Complete API documentation for the useFormContext hook.
useFormContext provides access to form context in deeply nested components:
import { useFormContext } from '@mapples/form';
const NestedComponent = () => {
const { form, submitting, submitForm, validationErrors } = useFormContext();
return (
<View>
<Button
title={submitting ? 'Submitting...' : 'Submit'}
onPress={submitForm}
disabled={submitting}
/>
{validationErrors && (
<Text style={{ color: 'red' }}>Validation errors occurred</Text>
)}
</View>
);
};
State Management Hooks
useFormState
Hook for accessing form state without re-rendering.
Function Reference: useFormState - Complete API documentation for the useFormState hook.
useFormState provides access to form state without causing re-renders:
import { useFormState } from '@mapples/form';
const FormStateDisplay = () => {
const { isValid, isDirty, isSubmitting, errorCount } = useFormState();
return (
<View>
<Text>Form is valid: {isValid ? 'Yes' : 'No'}</Text>
<Text>Form is dirty: {isDirty ? 'Yes' : 'No'}</Text>
<Text>Submitting: {isSubmitting ? 'Yes' : 'No'}</Text>
<Text>Error count: {errorCount}</Text>
</View>
);
};
useFormValue
Hook for watching specific form field values and changes.
Function Reference: useFormValue - Complete API documentation for the useFormValue hook.
useFormValue allows you to watch specific form field values:
import { useFormValue } from '@mapples/form';
const FormWatcher = () => {
const email = useFormValue('email');
const password = useFormValue('password');
return (
<View>
<Text>Current email: {email}</Text>
<Text>Current password length: {password?.length || 0}</Text>
</View>
);
};
Advanced Hooks
useFormSubmit
Hook for form submission handling.
Function Reference: useFormSubmit - Complete API documentation for the useFormSubmit hook.
useFormSubmit provides form submission functionality:
import { useFormSubmit } from '@mapples/form';
const FormWithSubmit = () => {
const submitForm = useFormSubmit();
const handleSubmit = () => {
submitForm();
};
return (
<View>
<Button title="Submit" onPress={handleSubmit} />
</View>
);
};
useFormHistory
Hook for managing form history and undo/redo functionality.
Function Reference: useFormHistory - Complete API documentation for the useFormHistory hook.
useFormHistory provides form history management:
import { useFormHistory } from '@mapples/form';
const FormWithHistory = () => {
const { canUndo, canRedo, undo, redo } = useFormHistory();
return (
<View>
<Button
title="Undo"
onPress={undo}
disabled={!canUndo}
/>
<Button
title="Redo"
onPress={redo}
disabled={!canRedo}
/>
</View>
);
};
Best Practices
Hook Composition
Combine multiple hooks for complex form functionality:
import { Form, useFormField, useFormArrayField, useFormContext } from '@mapples/form';
const ComplexForm = () => {
return (
<Form onSubmit={(data) => console.log('Form submitted:', data)}>
<UserInfoSection />
<TagsSection />
<SubmitSection />
</Form>
);
};
const UserInfoSection = () => {
const { value: name, setValue: setName } = useFormField('name', '');
const { value: email, setValue: setEmail } = useFormField('email', '');
return (
<View>
<TextInput value={name} onChangeText={setName} placeholder="Name" />
<TextInput value={email} onChangeText={setEmail} placeholder="Email" />
</View>
);
};
const TagsSection = () => {
const { value: tags, api } = useFormArrayField('tags', []);
return (
<View>
{tags?.map((tag, index) => (
<View key={index}>
<Text>{tag}</Text>
<Button title="Remove" onPress={() => api.remove(index)} />
</View>
))}
<Button title="Add Tag" onPress={() => api.push('New Tag')} />
</View>
);
};
const SubmitSection = () => {
const { form, submitting, submitForm } = useFormContext();
return (
<Button
title={submitting ? 'Submitting...' : 'Submit'}
onPress={submitForm}
disabled={submitting}
/>
);
};
Performance Optimization
Optimize your forms for better performance:
import { memo, useCallback } from 'react';
import { Form, useFormField } from '@mapples/form';
const OptimizedForm = memo(() => {
const onSubmit = useCallback((data) => {
console.log('Form submitted:', data);
}, []);
return (
<Form onSubmit={onSubmit}>
<OptimizedField />
</Form>
);
});
const OptimizedField = memo(() => {
const { value, setValue } = useFormField('username', '');
return (
<TextInput
value={value}
onChangeText={setValue}
placeholder="Username"
/>
);
});