Documented Idea of a <Form />

[q1b]

This documentation provides a quick and human-friendly guide to using the dynamic Form component. It's a powerful tool for building complex forms with minimal code by using a simple, declarative configuration object.

How is it different?

This form library stands out because it is schema-driven, allowing you to generate complex, dynamic forms by simply providing a configuration object. Unlike traditional form libraries where you manually write and manage JSX for each input, this component abstracts away the boilerplate.

Key differences include:

• Declarative Syntax: You describe what your form should contain (e.g., a text input, a fieldset, a dynamic list), and the component handles how to render it.
• Built-in Layouts: It automatically groups fields placed under the same key in the fields object, allowing for simple side-by-side layouts without manual CSS or component wrapping.
• Structural Components: It includes high-level types like fieldset for organizing sections and fieldlist for creating dynamic, repeatable lists with built-in add, remove, and reorder functionality.
• Clean Data Output: The form automatically flattens and structures the submitted data according to your schema, providing a clean JSON object that's ready to use.

It is going to be open-source!

---

🚀 Get Started

The Form component is driven by a single fields prop, a JavaScript object that defines your form's structure.

Here's a simple example of how to use it:

<Form
  fields={{
    name: { type: "text", label: "Your Name" },
    age: { type: "number", label: "Your Age" },
  }}
  onSubmit={(data) => {
    console.log("Form data submitted:", data);
  }}
/>

✨ Component Props

The component accepts just two core props:

Prop	Type	Required	Description
fields	Object	Yes	This is your form's blueprint. It's a configuration object that tells the component what inputs to render.
onSubmit	Function	Yes	A function that runs when the user submits the form. It receives the form data as a clean, structured object.

---

🧱 Building Your Form

The fields prop is the heart of the library. Here's a breakdown of how to configure it.

1. Grouping Fields

You can group related fields together to render them on the same line or in the same container. Simply place them under a common key in your fields object.

// These fields will render side-by-side
grouped: {
  name: { type: "text", label: "Name" },
  age: { type: "number", label: "Age" },
}

2. Defining a Field

Each field is an object with a few key-value pairs:

Key	Type	Required	Description
type	string	Yes	The type of input to display (e.g., "text", "date").
label	string	Yes	The text label for the field.
required	boolean	No	Add a * to the label to indicate a mandatory field.
defaultValue	any	No	Sets the initial value of the input.

---

🎨 Available Field Types

The component supports a variety of input and structural types.

Basic Inputs

These are your standard form fields for data collection.

• text - Standard single-line text input.
• number - Input for numerical values.
• textarea - Multi-line text area.
• date - A date picker input.
• checkbox - A checkbox input.
• select - A select input.
• multi-select - A multi-select input

Structural Fields

These are special types for organizing your form's layout and creating dynamic lists.

fieldset

Use fieldset to create a logical grouping of fields, often with a title, like a section for "Address" details.

address: {
  type: "fieldset",
  label: "Address",
  fields: {
    street: { type: "text", label: "Street" },
    city: { type: "text", label: "City" },
  }
}

fieldlist

Use fieldlist to create a dynamic, repeatable list of items. It's perfect for forms where users need to add or remove multiple entries, like a list of products.

• label: A title for the entire list.
• field: An object that defines the structure for each item in the list (often a fieldset).
• defaultValue: An array that pre-populates the list. Use [{}] to start with one empty item.

list: {
  type: "fieldlist",
  label: "List of Items",
  field: {
    type: "fieldset",
    label: "Item", // Label for each item in the list
    fields: {
      itemName: { type: "text", label: "Item Name" },
      quantity: { type: "number", label: "Quantity" }
    }
  },
  defaultValue: [{ itemName: "Orange", quantity: 12 }]
}

---

📝 Full Example

Here's the complete configuration for the form shown in the screenshot, combining all the features above.

<Form
  fields={{
    // Two fields on the same row
    grouped: {
      name: { type: "text", label: "Name" },
      age: { label: "Age", type: "number" }
    },
    // Another field group
    gr: {
      phoneNumber: { type: "textarea", label: "Phone Number", required: true },
      dateOfBirth: { type: "date", label: "Date of Birth", defaultValue: new Date() }
    },
    // A nested fieldset for the address
    address: {
      type: "fieldset",
      label: "Address",
      fields: {
        gr: {
          street: { type: "text", label: "Street" },
          city: { type: "text", label: "City" },
          zipCode: { type: "number", label: "Zip Code" }
        }
      }
    },
    // A dynamic list for adding items
    list: {
      type: "fieldlist",
      label: "List of Items",
      field: {
        type: "fieldset",
        label: "Item Object",
        fields: {
          as: {
            itemName: { type: "text", label: "Item Name" },
            quantity: { type: "number", label: "Quantity" }
          }
        }
      },
      defaultValue: [{}]
    }
  }}
  onSubmit={(data) => {
    console.log("Submitted Data:", data);
  }}
/>

✅ Clean Data Output

When submitted, the data object passed to onSubmit is automatically structured to match your fields configuration, making it easy to work with.

Example data output:

{
  "name": "John Doe",
  "age": 30,
  "phoneNumber": "555-1234",
  "dateOfBirth": "2025-09-19T11:12:53.000Z",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "zipCode": 12345
  },
  "list": [
    {
      "itemName": "Widget",
      "quantity": 5
    }
  ]
}