API Reference

Complete API documentation for all Formedible hooks, components, and utilities.

useFormedible Hook

The main hook for creating forms with Formedible. Returns form components and utilities.

Signature

function useFormedible<TFormValues>(
  config: FormedibleConfig<TFormValues>
): FormedibleReturn<TFormValues>

Configuration

interface FormedibleConfig<TFormValues> {
  // Required: Field definitions
  fields: FieldConfig[];
  
  // Optional: Zod schema for validation
  schema?: ZodSchema<TFormValues>;
  
  // Optional: TanStack Form options
  formOptions?: FormOptions<TFormValues>;
  
  // Optional: Cross-field validation
  crossFieldValidation?: CrossFieldValidation[];
  
  // Optional: Async validation
  asyncValidation?: Record<string, AsyncValidationConfig>;
  
  // Optional: Form persistence
  persistence?: PersistenceConfig;
  
  // Optional: Analytics tracking
  analytics?: AnalyticsConfig;
  
  // Optional: Layout configuration
  layout?: LayoutConfig;
}

Return Value

interface FormedibleReturn<TFormValues> {
  // Main form component
  Form: React.ComponentType;
  
  // TanStack Form instance
  form: FormApi<TFormValues>;
  
  // Cross-field validation errors
  crossFieldErrors: Record<string, string>;
  
  // Async validation states
  asyncValidationStates: Record<string, AsyncValidationState>;
  
  // Multi-page navigation
  currentPage: number;
  totalPages: number;
  goToNextPage: () => void;
  goToPreviousPage: () => void;
  goToPage: (page: number) => void;
  
  // Persistence utilities
  saveToStorage: (data: Partial<TFormValues>) => void;
  loadFromStorage: () => SavedFormData<TFormValues> | null;
  clearStorage: () => void;
  
  // Async validation utilities
  validateFieldAsync: (fieldName: string, value: any) => Promise<void>;
}

Field Configuration

Each field in the fields array follows this configuration structure:

Base Field Config

interface BaseFieldConfig {
  // Required
  name: string;
  type: FieldType;
  label: string;
  
  // Optional
  description?: string;
  placeholder?: string;
  required?: boolean;
  disabled?: boolean;
  className?: string;
  wrapperClassName?: string;
  
  // Multi-page support
  page?: number;
  
  // Conditional rendering
  condition?: (values: any) => boolean;
  
  // Help text
  help?: {
    text: string;
    tooltip?: string;
  };
  
  // Validation
  validation?: ZodSchema;
}

Field Types

Basic Fields

• text - Text input
• email - Email input
• password - Password input
• number - Number input
• tel - Phone input
• url - URL input
• textarea - Multi-line text

Selection Fields

• select - Dropdown select
• multiSelect - Multi-select
• radio - Radio buttons
• checkbox - Checkbox
• switch - Toggle switch

Advanced Fields

• date - Date picker
• file - File upload
• slider - Range slider
• rating - Star rating
• color - Color picker
• array - Dynamic arrays

Specialized Fields

• location - Location picker
• duration - Duration input
• autocomplete - Autocomplete
• masked - Masked input
• phone - Phone number

Validation Configuration

Cross-Field Validation

interface CrossFieldValidation {
  fields: string[];
  validator: (values: Record<string, any>) => string | null;
  message: string;
}

Async Validation

interface AsyncValidationConfig {
  validator: (value: any) => Promise<string | null>;
  debounceMs?: number;
  loadingMessage?: string;
}

Persistence Configuration

interface PersistenceConfig {
  key: string;
  storage: 'localStorage' | 'sessionStorage';
  debounceMs?: number;
  exclude?: string[];
  restoreOnMount?: boolean;
}

Analytics Configuration

interface AnalyticsConfig {
  onFormStart?: (timestamp: number) => void;
  onFormComplete?: (timeSpent: number, formData: any) => void;
  onFormAbandon?: (completionPercentage: number) => void;
  onFieldFocus?: (fieldName: string, timestamp: number) => void;
  onFieldBlur?: (fieldName: string, timeSpent: number) => void;
  onFieldChange?: (fieldName: string, value: any, timestamp: number) => void;
  onPageChange?: (fromPage: number, toPage: number, timeSpent: number) => void;
}

Testing Utilities

createFormTester

function createFormTester<TFormValues>(
  config: FormedibleConfig<TFormValues>,
  container?: HTMLElement
): FormTester<TFormValues>

interface FormTester<TFormValues> {
  render(): Promise<FormActions<TFormValues>>;
  setFormInstance(form: FormApi<TFormValues>): void;
}

interface FormActions<TFormValues> {
  // Field interactions
  fillField(name: string, value: any): Promise<void>;
  fillFields(values: Partial<TFormValues>): Promise<void>;
  triggerFieldFocus(name: string): Promise<void>;
  triggerFieldBlur(name: string): Promise<void>;
  
  // Form actions
  submitForm(): Promise<void>;
  resetForm(): Promise<void>;
  getFormData(): TFormValues;
  
  // Navigation
  goToPage(page: number): Promise<void>;
  nextPage(): Promise<void>;
  previousPage(): Promise<void>;
  
  // Assertions
  expectError(fieldName: string, message?: string): void;
  expectNoError(fieldName: string): void;
  expectValid(): void;
  expectInvalid(): void;
  expectFieldValue(fieldName: string, value: any): void;
  expectCurrentPage(page: number): void;
  
  // Async validation
  waitForAsyncValidation(fieldName: string): Promise<void>;
}

Type Definitions

// Main types exported by Formedible
export type {
  FormedibleConfig,
  FormedibleReturn,
  FieldConfig,
  BaseFieldConfig,
  CrossFieldValidation,
  AsyncValidationConfig,
  PersistenceConfig,
  AnalyticsConfig,
  LayoutConfig,
  FormTester,
  FormActions
};

// Field-specific types
export type {
  TextFieldConfig,
  SelectFieldConfig,
  DateFieldConfig,
  FileFieldConfig,
  LocationFieldConfig,
  DurationFieldConfig,
  AutocompleteFieldConfig,
  MaskedInputFieldConfig
};