Kingpin React Form

Super fast ReactJS forms with almost null overhead.

Features

• 🪶 Super light-weight - Zero dependencies (< 2kb gzip)
• 🌲 Tree shakable
• 🎯 Top rendering performance
• 😎 Declarative and easy to read
• 🔫 Battle tested
• 🔌 Pluggable/Extensible
• 🔖 Design System ready
• ⚙️ Native Typescript types

In few lines

Kingpin is a form library that aims to make the writing of forms on React easy like writing them directly on a HTML file.

To do it Kingpin lets each input to be just declared and forces it to follow the Single Responsibility Principle of each element (each input field take care just of it self).

The SRP lets each field to render independently without causing unhandled re-render side effects.

The main <Form /> component is the only interface for managing user set data, this choice in order to lead to a better forms develop and managing all the data in a single place (each state could be listened with the still available onChange element event).

Read more in the documentation.

Getting started

Install the package with your favourite package manager.

npm i kingpin-react-form

yarn add kingpin-react-form

Then create your form.

import { Error, Form, FormResult, Input } from 'kingpin-react-form'
import { FormEvent } from 'react'

function App(): JSX.Element {
  const submit = (e: FormEvent<HTMLFormElement>, form: FormResult) => {
    e.preventDefault()
    console.log(data)

    // data: {
    //     isValid: true,
    //     payload: {
    //       email: "",
    //       password: "",
    //       terms-acceptance: true
    //     }
    // }
  }

  return (
    <Form onSubmit={submit}>
      <Input name="email" type="email" />
      <Error name="email:error">The email doesn't exist</Error>
      <Input name="password" type="password" />
      <Error name="password:error">The password is wrong</Error>
      <Input name="terms-acceptance" type="checkbox" initialValue={true} />
      <button type="submit">Submit</button>
    </Form>
  )
}

Easy like a pie. Check how to handle errors in the documentation

Key concept

In order to make Kingpin efficient and reusable the entire state logic is managed within the <Form /> component (you shouldn't directly control each input value).

Each Kingpin action element (<Input />, <Textarea />, ...) needs a name prop in order to efficiently collect the result payload. The name should describe the input purpose; be aware of possible name conflicts!

Thanks to it the <Form /> is now able to easily handle the internal state, but how?

<Form /> is "just" a simple html <form>, so you can use it as usual. The most significant difference is that the onSubmit callback now takes two arguments: the "classic" event and an object which contains whether the form is valid or not (here about validation) and payload which is the name:value representation of its content.

Extend Kingpin inputs

Modern forms require more than just <input /> and <textarea /> components.

Kingpin plan is to add pluggable external components like Typeaheads, Slider, Dropdown ecc. specifically desinged and developed to work within a Kingpin Form.

In order to make Kingpin extensible by anyone it's possible create custom components with the withKingpin HOC.

To see how it works with a real example check the documentation.

Contributing

First off, thank you if you will consider to contribute to kingpin-react-form.

There are many ways to contribute like implementing a new feature, fixing bugs, improving the test suite or refining the documentation with fixes or examples.

The main kingpin's purpose is to be lightweight, full of functionalities and easy to work with. Be sure to follow this guidelines when you will do your implementation.

Any contribution or help will be appreciated.

License

This project is licensed under the MIT License - see the LICENSE file.