Smart Form
A powerful form component with built-in validation, mutation handling, and TypeScript support using Zod schemas and TanStack Query.
Installation
Install the Smart Form component using your preferred package manager.
Usage
The Smart Form component combines React Hook Form, Zod validation, and TanStack Query mutations to create a complete form solution with minimal boilerplate.
Discover Its Features
The Smart Form component is packed with powerful features designed to provide an exceptional user experience.
Zod Schema Validation
Built-in integration with Zod for runtime type safety and comprehensive validation rules.
TanStack Query Integration
Seamless integration with TanStack Query for mutations, loading states, and cache invalidation.
Multiple Field Types
Support for text, email, password, number, textarea, select, checkbox, radio, and color field types.
TypeScript Support
Full TypeScript support with type inference from Zod schemas for complete type safety.
Components
The Smart Form consists of the following components:
SmartForm
The main form component that provides form management with built-in validation, submission handling, and TanStack Query integration. It wraps the entire form and provides a render prop pattern for building form fields.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| schema | z.ZodSchema<T> | Required | Zod schema for form validation and type safety |
| mutationFn | (data: T) => Promise<any> | Required | Async function to handle form submission (API call) |
| queryKey | string[] | [] | TanStack Query key for cache invalidation after successful submission |
| mode | 'create' | 'edit' | 'create' | Form mode that affects submit button text and behavior |
| defaultValues | Partial<T> | undefined | Default values for form fields |
| onSuccess | (data: any) => void | undefined | Callback function called on successful form submission |
| onError | (error: Error) => void | undefined | Callback function called when form submission fails |
| submitText | string | undefined | Custom text for submit button (overrides mode-based text) |
| className | string | '' | Additional CSS classes for the form container |
| children | (form: UseFormReturn<T>) => React.ReactNode | Required | Render function that receives the form instance for building form fields |
SmartFormField
A versatile field component that renders different input types based on the type prop. Supports text, email, password, number, textarea, select, checkbox, radio, and color fields with automatic validation integration.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| form | UseFormReturn<T> | Required | React Hook Form instance passed from SmartForm |
| name | FieldPath<T> | Required | Field name that matches the schema property |
| type | 'text' | 'email' | 'password' | 'number' | 'textarea' | 'select' | 'checkbox' | 'radio' | 'color' | Required | Input type that determines the rendered field component |
| label | string | undefined | Label text displayed above the field |
| placeholder | string | undefined | Placeholder text for input fields |
| description | string | undefined | Help text displayed below the field |
| options | FormFieldOption[] | [] | Options for select and radio field types |
| disabled | boolean | false | Whether the field is disabled |
| className | string | '' | Additional CSS classes for the field container |
FormSection
A layout component for organizing form fields into logical groups with optional titles and descriptions. Helps create well-structured forms by separating different sections of information.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| title | string | Required | The title text displayed for the form section |
| description | string | undefined | Optional description text displayed below the title |
| children | React.ReactNode | Required | Form fields and other content to display in the section |
| className | string | '' | Additional CSS classes for styling the section |
ConditionalField
A utility component that conditionally renders child components based on the value of a watched form field. Useful for creating dynamic forms where certain fields appear based on user selections.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| form | UseFormReturn<T> | Required | React Hook Form instance passed from SmartForm |
| when | FieldPath<T> | Required | The field name to watch for changes |
| equals | any | Required | The value to compare against the watched field |
| children | React.ReactNode | Required | Content to render when the condition is met |