React Typed Form Kit

A modern, accessible, and performant type-safe form library for React with JSON-driven forms. Build beautiful, multi-step forms with animations, validation, and internationalization support.

✨ Features

• 📋 JSON-Driven Forms - Define forms using JSON configuration
• 🎭 TypeScript First - Full type safety and inference
• 🎨 Beautiful UI - Modern design with smooth animations
• 📱 Responsive - Works on all device sizes
• ♿ Accessible - WCAG 2.1 compliant
• 🌍 Internationalization - Built-in i18n support
• 🔄 Auto-Save - Draft functionality with localStorage
• 📊 Progress Tracking - Visual progress indicators
• 🎯 Validation - Comprehensive form validation
• 🖼️ Background Images - Support for form backgrounds
• 📖 Chapter Support - Multi-section forms
• 🎪 Nested Questions - Conditional question display

📦 Installation

npm install react-typed-form-kit
# or
yarn add react-typed-form-kit
# or
pnpm add react-typed-form-kit

CSS Import

Import the CSS file in your application:

import 'react-typed-form-kit/styles.css';

🚀 Quick Start

import React from 'react';
import { FormRenderer, FormDefinition } from 'react-typed-form-kit';
import 'react-typed-form-kit/styles.css';

const formDefinition: FormDefinition = {
  meta: {
    id: 'contact-form',
    title: { en: 'Contact Form', zh: '联系表单' },
    description: { en: 'Get in touch with us', zh: '与我们联系' },
    category: 'contact',
    estimatedTime: 3,
    totalQuestions: 3,
    languages: ['en', 'zh'],
  },
  config: {
    showProgressBar: true,
    allowBackNavigation: true,
  },
  questions: {
    name: {
      type: 'text',
      title: { en: 'Your Name', zh: '您的姓名' },
      validation: { required: true, minLength: 2 },
    },
    email: {
      type: 'email',
      title: { en: 'Email Address', zh: '电子邮箱' },
      validation: { required: true },
    },
    message: {
      type: 'textarea',
      title: { en: 'Message', zh: '消息' },
      validation: { required: true, minLength: 10 },
    },
  },
};

function App() {
  const handleSubmit = (data: any) => {
    console.log('Form submitted:', data);
  };

  return (
    <FormRenderer
      definition={formDefinition}
      onSubmit={handleSubmit}
      language="en"
    />
  );
}

export default App;

📚 Core Concepts

Form Definition

A form definition is a JSON object that describes your form structure:

interface FormDefinition {
  meta: FormMeta;           // Form metadata
  config: FormConfig;       // Form configuration
  questions: Questions;     // Form questions
  chapters?: Chapter[];     // Optional chapters for multi-section forms
}

Question Types

Supported question types:

• text - Single-line text input
• textarea - Multi-line text input
• email - Email input with validation
• phone - Phone number input
• number - Numeric input
• radio - Single choice from options
• checkbox - Multiple choice from options
• nested - Conditional questions based on parent answers

Validation

Built-in validation rules:

interface ValidationRules {
  required?: boolean;
  minLength?: number;
  maxLength?: number;
  min?: number;
  max?: number;
  pattern?: string;
  email?: boolean;
  phone?: boolean;
  custom?: (value: any) => string | undefined;
}

🎨 Styling & Theming

CSS Custom Properties

Customize the appearance using CSS custom properties:

:root {
  --form-primary: #3b82f6;
  --form-primary-hover: #2563eb;
  --form-background: #ffffff;
  --form-surface: #f8fafc;
  --form-text-primary: #1f2937;
  --form-text-secondary: #6b7280;
  --form-border: #e5e7eb;
  --form-error: #ef4444;
  --form-success: #10b981;
  
  --form-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --form-font-family-serif: Georgia, 'Times New Roman', serif;
  
  --form-border-radius: 0.5rem;
  --form-transition-fast: 150ms ease-in-out;
  --form-transition-normal: 250ms ease-in-out;
}

Background Images

Add background images to your forms:

const formWithBackground: FormDefinition = {
  // ... other config
  questions: {
    welcome: {
      type: 'text',
      title: { en: 'Welcome!' },
      background: {
        image: '/path/to/image.jpg',
        position: 'left' // 'left', 'right', or 'default'
      }
    }
  }
};

🌍 Internationalization

Support multiple languages:

// Define content in multiple languages
const multiLangForm: FormDefinition = {
  meta: {
    title: {
      en: 'Contact Form',
      zh: '联系表单'
    },
    // ...
  },
  questions: {
    name: {
      type: 'text',
      title: {
        en: 'What is your name?',
        zh: '您的姓名是什么？'
      },
      placeholder: {
        en: 'Enter your full name',
        zh: '请输入您的全名'
      }
    }
  }
};

// Use with language switching
function App() {
  const [language, setLanguage] = useState<Language>('en');
  
  return (
    <FormRenderer
      definition={multiLangForm}
      language={language}
      onLanguageChange={setLanguage}
      onSubmit={handleSubmit}
    />
  );
}

🔄 Advanced Features

Chapter-Based Forms

Create multi-section forms:

const chapterForm: FormDefinition = {
  meta: { /* ... */ },
  config: { /* ... */ },
  chapters: [
    {
      id: 'personal',
      title: { en: 'Personal Information' },
      questions: {
        name: { /* ... */ },
        email: { /* ... */ }
      }
    },
    {
      id: 'preferences',
      title: { en: 'Preferences' },
      questions: {
        newsletter: { /* ... */ },
        notifications: { /* ... */ }
      }
    }
  ]
};

Nested Questions

Show questions conditionally:

const conditionalForm: FormDefinition = {
  questions: {
    hasExperience: {
      type: 'radio',
      title: { en: 'Do you have experience?' },
      options: [
        {
          value: 'yes',
          label: { en: 'Yes' },
          nestedQuestions: [
            {
              id: 'yearsExperience',
              type: 'number',
              title: { en: 'How many years?' },
              validation: { required: true, min: 1 }
            }
          ]
        },
        {
          value: 'no',
          label: { en: 'No' }
        }
      ]
    }
  }
};

Draft Links & Auto-Save

Enable draft functionality:

<FormRenderer
  definition={formDefinition}
  onSubmit={handleSubmit}
  config={{
    autoSave: true,
    enableDraftLinks: true
  }}
/>

🎣 Hooks

useFormState

Manage form state manually:

import { useFormState } from 'react-typed-form-kit';

function CustomForm() {
  const {
    state,
    setAnswer,
    nextQuestion,
    previousQuestion,
    generateDraftLink
  } = useFormState(formDefinition);

  return (
    <div>
      {/* Custom form implementation */}
    </div>
  );
}

useKeyboardNavigation

Add keyboard shortcuts:

import { useKeyboardNavigation } from 'react-typed-form-kit';

function App() {
  useKeyboardNavigation({
    onNext: handleNext,
    onPrevious: handlePrevious,
    onSubmit: handleSubmit
  });

  return <FormRenderer /* ... */ />;
}

🎯 Validation

Built-in Validators

const validatedQuestion = {
  type: 'text',
  title: { en: 'Username' },
  validation: {
    required: true,
    minLength: 3,
    maxLength: 20,
    pattern: '^[a-zA-Z0-9_]+$' // Regex pattern
  }
};

Custom Validation

const customValidation = {
  type: 'text',
  title: { en: 'Password' },
  validation: {
    required: true,
    custom: (value: string) => {
      if (value.length < 8) return 'Password must be at least 8 characters';
      if (!/[A-Z]/.test(value)) return 'Password must contain uppercase letter';
      if (!/[0-9]/.test(value)) return 'Password must contain a number';
      return undefined; // Valid
    }
  }
};

📱 Responsive Design

The form automatically adapts to different screen sizes:

• Desktop: Full-width layout with side navigation
• Tablet: Optimized for touch interactions
• Mobile: Single-column layout with bottom navigation

♿ Accessibility

Built with accessibility in mind:

• ARIA labels and descriptions
• Keyboard navigation support
• Screen reader friendly
• High contrast support
• Focus management
• Error announcement

🔧 API Reference

FormRenderer Props

interface FormKitProps {
  definition: FormDefinition;
  onSubmit: (data: Record<string, any>) => void;
  language?: Language;
  initialValues?: Record<string, any>;
  draftId?: string;
  className?: string;
  onLanguageChange?: (language: Language) => void;
  onProgressChange?: (progress: number) => void;
}

Form Definition Schema

See the Wiki for complete schema documentation.

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide for details.

📄 License

MIT © William Li

🔗 Links

• Documentation
• Examples
• GitHub Repository
• NPM Package

Made with ❤️ by AltX Labs