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).

Why a new form library?

Current form libraries are too verbose causing a confusing development experience. They are also frequently very heavy and this is bad under many perspectives.

The main Kingpin purpose is to create a production ready library with a great development experience and a very little overhead.

That's basically it but there is another thing that requires a new form library.

Currently there are many ways to think about forms implementations:

• Using new FormData with the plain HTML validation systems (ref) (Hard to manage)
• Using useRef to handle the data on submit. (Easy to use but difficult to manage atomic errors)
• Using useState on each field. (Super easy to use but very low performances)

Kingpin wants to take the best from each of them ensuring a strong development experience and providing top performances and the most atomic level of interaction.

How hard is writing Kingpin's forms?

In short... easy like a pie.

Typescript

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>
  )
}

Javascript

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

function App() {
  const submit = (e, form) => {
    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>
  )
}

Check the next page for more details.

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.

Why the name "Kingpin"?

Kingpin is “JUST” a bolt in a skateboard truck but is where the entire steering mechanism rely on. Since its importance it's often very well engineer by truck companies with also many variants.

That's exactly what kingpin-react-form is: a super simple component, good engineered that allows your website to get the right direction.

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.