A powerful, configurable React form engine that generates dynamic forms from JSON configuration. Built with TypeScript, supports conditional rendering, validation, and complex form structures.
npm install z-quick-formsA powerful, configurable React form engine that generates dynamic forms from JSON configuration. Built with TypeScript, supports conditional rendering, validation, and complex form structures.
- Dynamic Form Generation: Create forms from JSON configuration
- Multiple Input Types: Support for text, select, radio, checkbox, signature, and more
- Conditional Rendering: Show/hide fields based on other field values
- Validation System: Built-in and custom validation with error handling
- Nested Forms: Unlimited nesting depth with parent-child relationships
- TypeScript Support: Full TypeScript definitions included
- Chakra UI Integration: Beautiful, accessible components out of the box
- Tailwind CSS Support: Custom styling with className props
- Form State Management: Built-in state tracking and form validation
``bash`
npm install z-quick-forms
This package only requires React as a peer dependency:
`bash`
npm install react
> Note: While this package works with any styling solution, it's optimized for use with Tailwind CSS. If you want to use Tailwind classes in your form configurations, you'll need to install and configure Tailwind CSS separately.
`tsx
import { FormEngine } from 'z-quick-forms';
function MyForm() {
const formConfig = [
{
question: 'What is your name?',
name: 'name',
type: 'text',
placeholder: 'Enter your name',
},
{
question: 'When is your birthday?',
name: 'birthday',
type: 'date',
},
];
return (
Submit={({ getData, isFormValid }) => (
onClick={() => {
const { isValid, data } = getData();
if (isValid) {
console.log('Form data:', data);
}
}}
disabled={!isFormValid()}
>
Submit
)}
/>
);
}
`
The FormEngine component accepts the following props:
| Prop | Type | Required | Description |
| -------------- | ------------------------- | -------- | ---------------------------------- |
| config | FormConfigProp[] | ✅ | Array of form field configurations |Submit
| | React.FC | ❌ | Custom submit component |constants
| | ConstantsType | ❌ | Global styling constants |stateTracker
| | (data: unknown) => void | ❌ | Callback for form state changes |
Each form field configuration supports the following properties:
#### Basic Properties
| Property | Type | Description |
| -------------- | ------------------ | --------------------------------------------- |
| question | string | The question/label for the field |name
| | string | Unique identifier for the field |type
| | string | HTML input type (text, email, password, etc.) |placeholder
| | string | Placeholder text for input fields |defaultValue
| | string \| number | Default value for the field |className
| | string | CSS classes for styling |disabled
| | boolean | Whether the field is disabled |
#### Advanced Properties
| Property | Type | Description |
| ---------------------- | --------------------- | ---------------------------------------- |
| complexType | ComplexType | Special input type (see below) |options
| | OptionsType[] | Options for select/radio/checkbox fields |validationConditions
| | CheckType[] | Validation rules |displayConditions
| | CheckType[] | Conditional rendering rules |customValidator
| | CustomValidatorType | Custom validation function |customElement
| | CustomElementType | Custom React component |
`tsx
// Text input
{
question: "What is your name?",
name: "name",
type: "text",
placeholder: "Enter your name"
}
// Email input
{
question: "What is your email?",
name: "email",
type: "email",
placeholder: "Enter your email"
}
// Password input
{
question: "Enter your password",
name: "password",
type: "password"
}
// Number input
{
question: "How old are you?",
name: "age",
type: "number"
}
// Date input
{
question: "When is your birthday?",
name: "birthday",
type: "date"
}
// Textarea
{
question: "Tell us about yourself",
name: "bio",
type: "textarea",
placeholder: "Write something..."
}
`
#### Select Dropdown
`tsx`
{
question: "Choose your country",
name: "country",
complexType: "SELECT",
options: ["USA", "Canada", "UK", "Australia"],
placeholder: "Select a country"
}
#### Multi-Select
`tsx`
{
question: "Select your interests",
name: "interests",
complexType: "MULTI-SELECT",
options: ["Sports", "Music", "Reading", "Travel"],
placeholder: "Choose multiple options"
}
#### Radio Group
`tsx`
{
question: "What is your gender?",
name: "gender",
complexType: "RADIO_GROUP",
options: ["Male", "Female", "Other"],
direction: "row" // or "column"
}
#### Checkbox
`tsx`
{
question: "Do you agree to the terms?",
name: "agree",
complexType: "CHECKBOX",
label: "I agree to the terms and conditions"
}
#### Multiple Checkboxes
`tsx`
{
question: "Select your favorite colors",
name: "colors",
complexType: "MULTIPLE_CHECKBOX",
options: ["Red", "Blue", "Green", "Yellow"],
noneOption: true // Adds "None" option
}
#### Signature
`tsx`
{
question: "Please sign here",
name: "signature",
complexType: "SIGNATURE"
}
#### Input Group
`tsx`
{
question: "Enter your phone number",
name: "phone",
complexType: "INPUT_GROUP",
group: {
type: "phone",
countryCode: "+1",
placeholder: "Enter phone number"
}
}
For select fields that need additional input values:
`tsx`
{
question: "Choose your subscription",
name: "subscription",
complexType: "SELECT_WITH_VALUE",
options: [
{
label: "Basic Plan",
optionalValue: true,
valuePlaceholder: "Enter custom amount",
valueType: "number"
},
{
label: "Premium Plan",
optionalValue: false
}
]
}
`tsx`
const config = [
{
question: 'Do you have a car?',
name: 'hasCar',
complexType: 'RADIO_GROUP',
options: ['Yes', 'No'],
},
{
question: 'What is your car model?',
name: 'carModel',
type: 'text',
displayConditions: [
{
attr: 'hasCar',
eq: 'Yes',
},
],
},
];
`tsx`
{
question: "Enter your age",
name: "age",
type: "number"
},
{
question: "Parent consent required",
name: "parentConsent",
complexType: "CHECKBOX",
displayConditions: [
{
attr: "age",
lt: 18
}
]
}
`tsx`
{
question: "Special discount code",
name: "discountCode",
type: "text",
displayConditions: [
{
attr: "age",
ge: 18
},
{
attr: "hasCar",
eq: "Yes"
}
]
}
`tsx`
{
question: "Enter your email",
name: "email",
type: "email",
defaultValidation: { enabled: true },
errorMessage: "Please enter a valid email address"
}
`tsx`
{
question: "Enter your username",
name: "username",
type: "text",
customValidator: (value, values, setError) => {
if (value === "admin") {
setError("Username 'admin' is reserved");
return true; // indicates error
}
if (value && value.length < 3) {
setError("Username must be at least 3 characters");
return true;
}
return false; // no error
}
}
`tsx`
{
question: "Confirm password",
name: "confirmPassword",
type: "password",
validationConditions: [
{
attr: "password",
eq: "confirmPassword",
errorMessage: "Passwords must match"
}
]
}
`tsx`
{
question: "Enter your age",
name: "age",
type: "number",
validationConditions: [
{
gt: 0,
errorMessage: "Age must be positive"
},
{
lt: 120,
errorMessage: "Age must be less than 120"
}
]
}
`tsx`
{
question: "What is your name?",
name: "name",
type: "text",
className: "w-full px-4 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500"
}
`tsx`
constants={{
question: {
className: 'text-lg font-semibold text-gray-800 mb-2',
style: { color: '#374151' },
},
}}
Submit={SubmitComponent}
/>
`tsx`
{
question: "Enter your email",
name: "email",
type: "email",
errorClassName: "text-red-500 text-sm mt-1"
}
`tsx`
{
question: "Upload your file",
name: "file",
customElement: ({ name, onChange, disabled }) => (
type="file"
onChange={(e) => onChange(e.target.files?.[0]?.name || "")}
disabled={disabled}
className="block w-full text-sm text-gray-500 file:mr-4 file:py-2 file:px-4 file:rounded-full file:border-0 file:text-sm file:font-semibold file:bg-blue-50 file:text-blue-700 hover:file:bg-blue-100"
/>
)
}
`tsx`
stateTracker={(data) => {
console.log('Form state changed:', data);
// Save to localStorage, send to server, etc.
}}
Submit={SubmitComponent}
/>
`tsx
const SubmitComponent = ({ getData, isFormValid, data }) => {
const handleSubmit = () => {
const { isValid, data: cleanData } = getData();
if (isValid) {
console.log('Submitting:', cleanData);
// Send data to server
} else {
console.log('Form has errors');
}
};
return (
onClick={handleSubmit}
disabled={!isFormValid()}
className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
>
Submit Form
);
};
`
`tsx
import React from 'react';
import { FormEngine } from 'z-quick-forms';
function RegistrationForm() {
const config = [
{
question: 'What is your full name?',
name: 'fullName',
type: 'text',
placeholder: 'Enter your full name',
defaultValidation: { enabled: true },
},
{
question: 'What is your email address?',
name: 'email',
type: 'email',
placeholder: 'Enter your email',
validationConditions: [
{
contains: '@',
errorMessage: 'Please enter a valid email address',
},
],
},
{
question: 'How old are you?',
name: 'age',
type: 'number',
validationConditions: [
{
gt: 0,
errorMessage: 'Age must be positive',
},
{
lt: 120,
errorMessage: 'Age must be less than 120',
},
],
},
{
question: "Do you have a driver's license?",
name: 'hasLicense',
complexType: 'RADIO_GROUP',
options: ['Yes', 'No'],
},
{
question: 'What type of vehicle do you drive?',
name: 'vehicleType',
complexType: 'SELECT',
options: ['Car', 'Motorcycle', 'Truck', 'Other'],
displayConditions: [
{
attr: 'hasLicense',
eq: 'Yes',
},
],
},
{
question: 'Select your interests',
name: 'interests',
complexType: 'MULTIPLE_CHECKBOX',
options: ['Sports', 'Music', 'Reading', 'Travel', 'Cooking'],
noneOption: true,
},
{
question: 'Tell us about yourself',
name: 'bio',
type: 'textarea',
placeholder: 'Write a short bio...',
},
{
question: 'Please sign to confirm',
name: 'signature',
complexType: 'SIGNATURE',
displayConditions: [
{
attr: 'age',
ge: 18,
},
],
},
];
const SubmitButton = ({ getData, isFormValid }) => (
onClick={() => {
const { isValid, data } = getData();
if (isValid) {
console.log('Registration data:', data);
// Submit to server
}
}}
disabled={!isFormValid()}
className="w-full px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed"
>
Register
);
return (
export default RegistrationForm;
`
| Property | Description | Example |
| ---------- | --------------------- | ----------------------------------------- |
| eq | Equal to | { attr: "age", eq: 18 } |ne
| | Not equal to | { attr: "status", ne: "inactive" } |gt
| | Greater than | { attr: "score", gt: 80 } |lt
| | Less than | { attr: "age", lt: 65 } |ge
| | Greater than or equal | { attr: "quantity", ge: 1 } |le
| | Less than or equal | { attr: "price", le: 100 } |contains
| | Contains substring | { attr: "email", contains: "@" } |isIn
| | Value is in array | { attr: "country", isIn: ["US", "CA"] } |len
| | Length check | { attr: "password", len: 8 } |
`tsx`
{
if: { attr: "userType", eq: "premium" },
then: [
{ attr: "age", ge: 18 },
{ attr: "email", contains: "@" }
],
errorMessage: "Premium users must be 18+ with valid email"
}
The form engine provides comprehensive error handling:
- Validation Errors: Displayed below each field
- Form Validation: Prevents submission when errors exist
- Custom Error Messages: Configurable error text
- Error Styling: Customizable error appearance
The package is optimized for size:
- Minified: ~10KB
- Gzipped: ~3KB
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
MIT License - see LICENSE file for details.
For issues and questions:
- Create an issue on GitHub
- Check the examples in the /example directory
- Review the TypeScript definitions for detailed type information
- parent property is deprecated, use displayConditions insteaddisplayCondition
- function is deprecated, use displayConditions arrayadditionalInputs
- is deprecated, use displayConditions for nested fieldscustomValidator
- is deprecated, use validationConditions for better performance
`tsx
// ❌ Old way (deprecated)
{
question: "Child field",
name: "child",
parent: "parentField"
}
// ✅ New way
{
question: "Child field",
name: "child",
displayConditions: [
{ attr: "parentField", eq: true }
]
}
``
---
Built with ❤️ using React, TypeScript, and Chakra UI