API Reference

Complete API Documentation

Everything you need to know about Formedible hooks, components, and utilities. Build powerful, type-safe forms with comprehensive configuration options.

Hooks & Config

Type Definitions

Testing Utils

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

Configure cross-field and async validation for complex form requirements.

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

Configure form data persistence to localStorage or sessionStorage.

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

Analytics Configuration

Track form interactions and user behavior for insights.

interface AnalyticsConfig {
  // Form lifecycle events
  onFormStart?: (timestamp: number) => void;
  onFormComplete?: (timeSpent: number, formData: any) => void;
  onFormAbandon?: (completionPercentage: number, context?: any) => void;
  
  // Field interaction events
  onFieldFocus?: (fieldName: string, timestamp: number) => void;
  onFieldBlur?: (fieldName: string, timeSpent: number) => void;
  onFieldChange?: (fieldName: string, value: any, timestamp: number) => void;
  onFieldError?: (fieldName: string, errors: string[], timestamp: number) => void;
  onFieldComplete?: (fieldName: string, isValid: boolean, timeSpent: number) => void;
  
  // Multi-page/tab form events
  onPageChange?: (fromPage: number, toPage: number, timeSpent: number, context?: any) => void;
  onTabChange?: (fromTab: string, toTab: string, timeSpent: number, context?: any) => void;
  onTabFirstVisit?: (tabId: string, timestamp: number) => void;
  
  // Performance tracking
  onSubmissionPerformance?: (totalTime: number, validationTime: number, processingTime: number) => void;
}

Type Definitions

All TypeScript types exported by Formedible for type-safe development.

// 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
};

Ready to Build Amazing Forms?

Now that you know the API, start building powerful forms with Formedible. Create beautiful, type-safe forms with comprehensive validation and features.

Get Started Try Builder