Formwix

Dynamic form generation for React applications

Formwix is a powerful React library that enables developers to create dynamic, customizable forms through a simple configuration-based approach. Built on top of react-hook-form, Formwix combines the flexibility of custom form building with robust validation capabilities.

Features

Configuration-based form generation - Create complex forms with minimal code
Built-in validation - Leverage the power of react-hook-form for form validation
Customizable theming - Style your forms globally or at the individual field level
Responsive design - Forms adapt to different screen sizes

Installation

# Using npm
npm install formwix

# Using yarn
yarn add formwix

# Using pnpm
pnpm add formwix

Quick Start

import { Formwix, TypeFieldConfig, TypeFormConfig } from "formwix";
import { toast } from "sonner";
import "formwix/dist/formwix.css";

// Define your form fields
const fields: TypeFieldConfig[] = [
  {
    type: "email",
    label: "Email",
    name: "email",
    placeholder: "Enter your email",
    validation: {
      required: { value: true, message: "Email is required" },
    },
  },
  {
    type: "password",
    label: "Password",
    name: "password",
    placeholder: "Enter your password",
    validation: {
      required: { value: true, message: "Password is required" },
      minLength: {
        value: 6,
        message: "Password must be at least 6 characters",
      },
    },
  },
];

// Configure your form
const config: TypeFormConfig = {
  fields,
  submitButtonLabel: "Login",
  onSubmit: (values, { reset }) => {
    toast.success("Form submitted successfully!");
    reset();
  },
};

// Use the Formwix component
export default function LoginForm() {
  return <Formwix config={config} />;
}

Core Concepts

Form Configuration

Forms in Formwix are defined using a configuration object that specifies fields, validation rules, and submission behavior.

TypeFormConfig

Property	Type	Description
`fields`	`TypeFieldConfig[]`	Array of field configurations
`submitButtonLabel`	`string`	Label for the submit button
`onSubmit`	`(data, formUtils) => void`	Function called when form is submitted
`defaultValues`	`TypeFormData`	Default values for the form fields
`showFormResetButton`	`boolean`	Whether to show a reset button
`resetButtonLabel`	`string`	Label for the reset button
`validationMode`	`string`	Defines the validation behaviour

Field Configuration

Each field in the form is defined using a field configuration object.

TypeFieldConfig

Property	Type	Description
`type`	`string`	Type of the field (e.g., "text", "email", "password")
`name`	`string`	Name of the field (used as the form data key)
`label`	`string`	Label displayed for the field
`placeholder`	`string` (optional)	Placeholder text for the field
`value`	`string` (optional)	Initial value for the field
`validation`	`TypeValidationRules` (optional)	Validation rules for the field
`description`	`string` (optional)	Description displayed below the field
`theme`	`Partial<typeof defaultTheme>` (optional)	Field-specific theme overrides
`disabled`	`boolean` (optional)	Whether the field is disabled

Validation

Formwix leverages react-hook-form for validation and provides a simple interface to define validation rules.

TypeValidationRules

Property	Type	Description
`min`	`TypeGenericValidationRule`	Minimum value
`max`	`TypeGenericValidationRule`	Maximum value
`minLength`	`TypeGenericValidationRule`	Minimum length
`maxLength`	`TypeGenericValidationRule`	Maximum length
`pattern`	`TypeGenericValidationRule`	Regular expression pattern
`required`	`TypeGenericValidationRule`	Whether the field is required

Theming

Formwix provides a flexible theming system that allows you to customize the appearance of your forms.

Default Theme

Formwix comes with a default theme that you can override either globally or at the field level.

// Default theme classes
const defaultTheme = {
  form: "df-form",
  formContainer: "df-form-container",
  fieldContainer: "df-field-container",
  fieldWrapper: "df-field-wrapper",
  fieldLabelWrapper: "df-field-label-wrapper",
  label: "df-label",
  optionsLabel: "df-options-label",
  requiredLabel: "df-required-label",
  fieldDescription: "df-field-description",
  fieldError: "df-field-error",
  text: "df-text",
  email: "df-email",
  tel: "df-tel",
  textarea: "df-textarea",
  number: "df-number",
  date: "df-date",
  passwordWrapper: "df-password-wrapper",
  password: "df-password",
  passwordEyeButtonWrapper: "df-password-eye-button-wrapper",
  passwordEyeButton: "df-password-eye-button",
  passwordEyeCloseButton: "df-password-eye-close-button",
  checkBoxWrapper: "df-checkbox-wrapper",
  checkbox: "df-checkbox",
  checkBoxLabel: "df-checkbox-label",
  selectOptionsWrapper: "df-select-options-wrapper",
  select: "df-select",
  radioWrapper: "df-radio-wrapper",
  radioOptionsWrapper: "df-radio-options-wrapper",
  multiSelectWrapper: "df-multi-select-wrapper",
  multiSelect: "df-multi-select",
  multiSelectOptionsWrapper: "df-multi-select-options-wrapper",
  radio: "df-radio",
  formActionWrapper: "df-form-action-wrapper",
  submitButton: "df-submit-button",
  formResetButton: "df-form-reset-button",
  time: "df-time",
  url: "df-url",
};

Custom Theming

To apply custom styles, pass a theme object to the Formwix component:

<Formwix
  config={config}
  theme={{
    email: "border border-gray-300 w-full py-2 px-2 rounded-lg outline-none",
    passwordWrapper:
      "border flex justify-end items-center relative border-gray-300 w-full py-2 px-2 rounded-lg",
    submitButton: "bg-black text-white w-full py-2 rounded-lg",
  }}
/>

Global Theming

Apply styles globally by passing a theme object to the Formwix component.

Field-Level Theming

Override styles for specific fields by including a theme property in the field configuration:

const fields: TypeFieldConfig[] = [
  {
    type: "email",
    label: "Email",
    name: "email",
    theme: {
      email: "border-2 border-blue-500 rounded-md p-2",
    },
  },
];

Field Types

Formwix supports various field types to address different input needs:

Type	Description
`text`	Single-line text input
`email`	Email input with validation
`password`	Password input with show/hide functionality
`tel`	Telephone number input
`number`	Numeric input
`date`	Date picker
`time`	Time picker
`url`	URL input with validation
`textarea`	Multi-line text input
`select`	Dropdown selection
`radio`	Radio button group
`checkbox`	Checkbox input
`multiSelect`	Multiple selection dropdown
`datetime-local`	Date and time picker

Examples

Login Form

import { Formwix, TypeFieldConfig, TypeFormConfig } from "formwix";

const fields: TypeFieldConfig[] = [
  {
    type: "email",
    label: "Email",
    name: "email",
    placeholder: "Enter your email",
    validation: {
      required: { value: true, message: "Email is required" },
    },
  },
  {
    type: "password",
    label: "Password",
    name: "password",
    placeholder: "Enter your password",
    validation: {
      required: { value: true, message: "Password is required" },
      minLength: {
        value: 6,
        message: "Password must be at least 6 characters",
      },
    },
  },
];

const config: TypeFormConfig = {
  fields,
  submitButtonLabel: "Login",
  onSubmit: (values, { reset }) => {
    console.log(values);
    // Handle form submission
  },
};

export default function LoginForm() {
  return <Formwix config={config} />;
}

Contact Form

import { Formwix, TypeFieldConfig, TypeFormConfig } from "formwix";

const fields: TypeFieldConfig[] = [
  {
    type: "text",
    label: "Name",
    name: "name",
    placeholder: "Enter your full name",
    validation: {
      required: { value: true, message: "Name is required" },
    },
  },
  {
    type: "email",
    label: "Email",
    name: "email",
    placeholder: "Enter your email",
    validation: {
      required: { value: true, message: "Email is required" },
    },
  },
  {
    type: "tel",
    label: "Phone",
    name: "phone",
    placeholder: "Enter your phone number",
  },
  {
    type: "select",
    label: "Subject",
    name: "subject",
    options: [
      { label: "General Inquiry", value: "general" },
      { label: "Support", value: "support" },
      { label: "Feedback", value: "feedback" },
    ],
    validation: {
      required: { value: true, message: "Subject is required" },
    },
  },
  {
    type: "textarea",
    label: "Message",
    name: "message",
    placeholder: "Enter your message",
    validation: {
      required: { value: true, message: "Message is required" },
      minLength: {
        value: 10,
        message: "Message must be at least 10 characters",
      },
    },
  },
];

const config: TypeFormConfig = {
  fields,
  submitButtonLabel: "Send Message",
  onSubmit: (values, { reset }) => {
    console.log(values);
    // Handle form submission
    reset();
  },
};

export default function ContactForm() {
  return <Formwix config={config} />;
}

API Reference

Components

Formwix

The main component for generating forms.

import { Formwix } from "formwix";

<Formwix config={formConfig} theme={customTheme} />;

Props

Prop	Type	Description
`config`	`TypeFormConfig`	Form configuration object
`theme`	`Partial<typeof defaultTheme>`	Theme overrides

Type Definitions

TypeFormConfig

Defines the overall form configuration.

export interface TypeFormConfig {
  fields: TypeFieldConfig[];
  submitButtonLabel?: string;
  validationMode?: "onBlur" | "onChange" | "onSubmit" | "onTouched" | "all";
  onSubmit: (data: TypeFormData, formUtils: TypeFormUtils) => void;
  defaultValues?: TypeFormData;
  showFormResetButton?: boolean;
  resetButtonLabel?: string;
}

TypeFieldConfig

Defines the structure of form fields.

export interface TypeFieldConfig {
  type: string;
  name: string;
  label: string;
  placeholder?: string;
  value?: string;
  validation?: TypeValidationRules;
  description?: string;
  theme?: Partial<typeof defaultTheme>;
  disabled?: boolean;
}

TypeValidationRules

Defines validation rules for fields.

export interface TypeValidationRules {
  min?: TypeGenericValidationRule;
  max?: TypeGenericValidationRule;
  minLength?: TypeGenericValidationRule;
  maxLength?: TypeGenericValidationRule;
  pattern?: TypeGenericValidationRule;
  required?: TypeGenericValidationRule;
}

TypeFormUtils

Provides utilities for form manipulation.

export interface TypeFormUtils {
  reset: () => void;
}

Advanced Usage

Dynamic Form Generation

You can dynamically generate form fields based on data:

import { Formwix, TypeFieldConfig, TypeFormConfig } from "formwix";

function DynamicForm({ schema }) {
  // Transform schema into Formwix field configuration
  const fields: TypeFieldConfig[] = schema.map((item) => ({
    type: item.fieldType,
    label: item.label,
    name: item.name,
    placeholder: item.placeholder,
    validation: item.validation,
  }));

  const config: TypeFormConfig = {
    fields,
    submitButtonLabel: "Submit",
    onSubmit: (values) => {
      console.log(values);
    },
  };

  return <Formwix config={config} />;
}

Multi-step Forms

Create multi-step forms by conditionally rendering different Formwix components:

import { useState } from "react";
import { Formwix, TypeFieldConfig, TypeFormConfig } from "formwix";

function MultiStepForm() {
  const [step, setStep] = useState(1);
  const [formData, setFormData] = useState({});

  const handleStep1Submit = (data) => {
    setFormData({ ...formData, ...data });
    setStep(2);
  };

  const handleStep2Submit = (data) => {
    const finalData = { ...formData, ...data };
    console.log("Final form data:", finalData);
    // Submit final data
  };

  const step1Fields: TypeFieldConfig[] = [
    // Step 1 fields
  ];

  const step2Fields: TypeFieldConfig[] = [
    // Step 2 fields
  ];

  const step1Config: TypeFormConfig = {
    fields: step1Fields,
    submitButtonLabel: "Next",
    onSubmit: handleStep1Submit,
  };

  const step2Config: TypeFormConfig = {
    fields: step2Fields,
    submitButtonLabel: "Submit",
    onSubmit: handleStep2Submit,
    defaultValues: formData,
  };

  return (
    <div>
      {step === 1 && <Formwix config={step1Config} />}
      {step === 2 && <Formwix config={step2Config} />}
    </div>
  );
}

Field Type Examples

Below are examples of how to configure each supported field type in Formwix.

Text Field

{
  type: "text",
  name: "textField",
  label: "Text Field",
  placeholder: "Enter text",
  validation: {
    required: { value: true, message: "Required" },
    minLength: { value: 3, message: "Minimum 3 characters required" },
    maxLength: { value: 30, message: "Maximum 30 characters allowed" },
  }
}

Email Field

{
  type: "email",
  name: "email",
  label: "Email",
  placeholder: "Enter your email",
  validation: {
    required: { value: true, message: "Email is required" },
  }
}

Password Field

{
  type: "password",
  name: "password",
  label: "Password",
  placeholder: "Enter your password",
  validation: {
    required: { value: true, message: "Password is required" },
    minLength: { value: 8, message: "Password must be at least 8 characters" },
    containUpperCase: { value: true, message: "Password must contain at least one uppercase letter" },
    containLowerCase: { value: true, message: "Password must contain at least one lowercase letter" },
    containNumber: { value: true, message: "Password must contain at least one number" },
    containSpecialChar: { value: true, message: "Password must contain at least one special character" },
    matchField:  { field:  "password", message:  "Passwords do not match"},
  }
}

Number Field

{
  type: "number",
  name: "quantity",
  label: "Quantity",
  placeholder: "Enter quantity",
  validation: {
    required: { value: true, message: "Quantity is required" },
    min: { value: 1, message: "Minimum quantity is 1" },
    max: { value: 100, message: "Maximum quantity is 100" }
  }
}

Select Field

{
  type: "select",
  name: "country",
  label: "Country",
  placeholder: "Select your country",
  options: [
    { label: "United States", value: "us" },
    { label: "Canada", value: "ca" },
    { label: "United Kingdom", value: "uk" }
  ],
  validation: {
    required: { value: true, message: "Please select a country" }
  }
}

Textarea Field

{
  type: "textarea",
  name: "description",
  label: "Description",
  placeholder: "Enter description",
  rows: 4,
  validation: {
    required: { value: true, message: "Description is required" },
    maxLength: { value: 500, message: "Maximum 500 characters allowed" }
  }
}

Checkbox Field

{
  type: "checkbox",
  name: "terms",
  label: "I agree to the terms and conditions",
  validation: {
    required: { value: true, message: "You must agree to the terms" }
  }
}

Radio Field

{
  type: "radio",
  name: "gender",
  label: "Gender",
  options: [
    { label: "Male", value: "male" },
    { label: "Female", value: "female" },
    { label: "Other", value: "other" }
  ],
  validation: {
    required: { value: true, message: "Please select a gender" }
  }
}

Tel Field

{
  type: "tel",
  name: "tel",
  label: "Phone No.",
  placeholder: "Enter Phone Number",
  validation: {
    required: { value: true, message: "Required" },
    minLength: { value: 3, message: "Minimum 3 characters required" },
    maxLength: { value: 50, message: "Maximum 50 characters allowed" },
    pattern: { value: `/^[0-9]*$/`, message: "Only numbers are allowed" }
  }
}

URL Field

{
  type: "url",
  name: "website",
  label: "Website",
  placeholder: "Enter your website URL",
  validation: {
    required: { value: true, message: "URL is required" }
  }
}

DateTime-Local Field

{
  type: "datetime-local",
  name: "appointment",
  label: "Appointment Time",
  validation: {
    required: { value: true, message: "Appointment time is required" },
    minDate: { value: "2024-01-01T00:00", message: "Appointment must be after January 1, 2024" }
  }
}

Time Field

{
  type: "time",
  name: "time",
  label: "Time",
  validation: {
    required: { value: true, message: "Time is required" }
  }
}

Date Field

{
  type: "date",
  name: "dob",
  label: "Date of Birth",
  validation: {
    required: { value: true, message: "Date of birth is required" },
    minDate: { value: "1990-01-01", message: "Date must be after 1990" },
    maxDate: { value: "2025-12-31", message: "Date cannot be after 2025" }
  }
}

Multi-Select Field

{
  type: "multiselect",
  name: "skills",
  label: "Skills",
  options: [
    { label: "JavaScript", value: "js" },
    { label: "TypeScript", value: "ts" },
    { label: "React", value: "react" },
    { label: "Node.js", value: "node" }
  ],
  validation: {
    required: { value: true, message: "Please select at least one skill" }
  }
}

Best Practices

Use meaningful field names: Choose field names that reflect their purpose for better code readability.
Provide clear validation messages: Help users understand what went wrong when validation fails.
Use field descriptions: Add descriptions to complex fields to guide users.
Keep forms focused: Each form should have a clear purpose and collect only necessary information.
Use appropriate field types: Choose the right field type for each input to improve the user experience.
Test form validation: Ensure your validation rules work as expected.

Troubleshooting

Common Issues

Problem: Form isn't submitting.

Solution: Check if your validation rules are preventing submission. Look for validation errors in the form.

Problem: Custom styles aren't applying.

Solution: Ensure you're importing the CSS file and check the specificity of your CSS selectors.

Problem: Form values aren't being cleared after submission.

Solution: Make sure you're calling the reset() function in your onSubmit handler.

Documentation

For more detailed documentation and examples, visit docs

Documentation

Resources

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

formwix

Formwix

Features

Installation

Quick Start

Core Concepts

Form Configuration

TypeFormConfig

Field Configuration

TypeFieldConfig

Validation

TypeValidationRules

Theming

Default Theme

Custom Theming

Global Theming

Field-Level Theming

Field Types

Examples

Login Form

Contact Form

API Reference

Components

Formwix

Props

Type Definitions

TypeFormConfig

TypeFieldConfig

TypeValidationRules

TypeFormUtils

Advanced Usage

Dynamic Form Generation

Multi-step Forms

Field Type Examples

Text Field

Email Field

Password Field

Number Field

Select Field

Textarea Field

Checkbox Field

Radio Field

Tel Field

URL Field

DateTime-Local Field

Time Field

Date Field

Multi-Select Field

Best Practices

Troubleshooting

Common Issues

Documentation

Resources

Contributing

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads