## ๐ก What is Usetheform?
**Usetheform** is a lightweight, dependency-free React library for composing **declarative forms** and managing their state. It's simple to use, flexible, and powerful for handling nested fields, validation, and much more.
๐ [Documentation](https://iusehooks.github.io/usetheform/)
โก [Quickstart](#zap-quickstart)
๐ฅ [Features](#fire-features)
๐ [Recipes](#book-recipes)
๐ง [Motivation](#brain-motivation)
๐งช [Code Sandboxes](#code-sandboxes)
๐ค [How to Contribute](#how-to-contribute)
๐ [License](#license)
## :fire: Features
- ๐ฆ Easy integration with libraries like [React Select/Material UI](https://codesandbox.io/s/materialuireactselect-6ufc2) and [React Dropzone/Material UI Dropzone](https://codesandbox.io/s/reactdropzone-materialuidropzone-yjb8w)
- โ Sync and Async validation at:
- [Form level](https://iusehooks.github.io/usetheform/components/Form#validatisync)
- [Field level](https://iusehooks.github.io/usetheform/components/Input#validatisync)
- [Collection level](https://iusehooks.github.io/usetheform/components/Collection#validatisync)
- ๐ Schema validation with:
- [Yup](https://codesandbox.io/p/sandbox/schema-validations-uc1m6?file=%2Fsrc%2FFormYUP.jsx)
- [Zod](https://codesandbox.io/p/sandbox/schema-validations-uc1m6?file=%2Fsrc%2FFormZOD.jsx)
- [Superstruct](https://codesandbox.io/p/sandbox/schema-validations-uc1m6?file=%2Fsrc%2FFormSuperStruct.jsx)
- [Joi](https://codesandbox.io/p/sandbox/schema-validations-uc1m6?file=%2Fsrc%2FFormJOI.jsx)
- ๐งฌ Follows native HTML standards โ [see in action](https://codesandbox.io/s/built-informvalidation-lp672?file=/src/Info.jsx)
- ๐ง Reducer support at:
- [Form level](https://iusehooks.github.io/usetheform/components/Form/#reducers)
- [Field level](https://iusehooks.github.io/usetheform/components/Input#reducers)
- [Collection level](https://iusehooks.github.io/usetheform/components/Collection#reducers)
- ๐งฉ Easy handling of arrays, objects, and nested structures
- [Nested collections demo](https://iusehooks.github.io/usetheform/components/Collection#nested-collections)
- ๐ฆ Tiny bundle size, zero dependencies โ [Check it on Bundlephobia](https://bundlephobia.com/result?p=usetheform)
## :zap: Quickstart
Install `usetheform` using your preferred package manager:
```bash
npm install --save usetheform
```
```bash
yarn add usetheform
```
#### Basic usage example:
```tsx
import React from "react";
import { Form, Input, useValidation } from "usetheform";
import { ReducerFn, ValidatorFn, OnChangeFormFn, OnSubmitFormFn } from "usetheform/types";
interface MyFormState {
firstname: string;
lastname: string;
age: number;
}
const preventNegativeNumber: ReducerFn = (next) =>
next <= 0 ? 0 : next;
const required: ValidatorFn = (value) =>
value?.trim() ? undefined : "Required";
export default function App() {
const onChange: OnChangeFormFn = (formState) => console.log("ON_CHANGE:", formState);
const onSubmit: OnSubmitFormFn = (formState) => console.log("ON_SUBMIT:", formState);
const [status, validation] = useValidation([required]);
return (
onSubmit={onSubmit} onChange={onChange}>
{status.error && {status.error}}
);
}
```
## :book: Recipes
### Accessing form fields outside the Form context
#### ๐งฑ Step 1: Create a form store
```tsx
interface FormState { counter: number; }
```
```tsx
import { createFormStore } from 'usetheform';
const [formStore, useFormSelector] = createFormStore({ counter: 0 });
export const awesomeFormStore = formStore;
export const useAwesomeFormSelector = useFormSelector;
```
#### ๐งฉ Step 2: Create your awesome form
```tsx
import { Form, Input } from 'usetheform';
import { awesomeFormStore } from './awesomeFormStore';
export default function AwesomeForm() {
return (
<>
formStore={awesomeFormStore}>
);
}
```
#### ๐ Step 3: Connect your components
```tsx
import { useAwesomeFormSelector } from './awesomeFormStore';
export const Counter = () => {
const [counter, setCounterValue] = useAwesomeFormSelector<"counter">((state) => state.counter);
return (
{counter}
);
};
```
## :brain: Motivation
**Usetheform** was created to provide a highly flexible, declarative way to handle forms in React with no dependencies. It supports:
- Nested field structures
- Synchronous & asynchronous validation
- Custom input and reducer logic
- Schema-based validation
- Tiny footprint
If you find this library useful, please โญ the repo. It means a lot! ๐
## ๐ค Author
- **Antonio Pangallo** โ [@antonio_pangall](https://twitter.com/antonio_pangall)
### โญ Stargazers
[](https://github.com/iusehooks/usetheform/stargazers)
## Code Sandboxes
- [Twitter-style Form Bar](https://codesandbox.io/s/twitter-bar-form-czx3o)
- [Shopping Cart](https://codesandbox.io/s/shopping-cart-97y5k)
- [Form Examples (Select, Slider, Collections)](https://codesandbox.io/s/formexample2-mmcjs)
- [Various Implementations](https://codesandbox.io/s/035l4l75ln)
- [Wizard](https://codesandbox.io/s/v680xok7k7)
- [FormContext](https://codesandbox.io/s/formcontext-ukvc5)
- [Material UI + React Select](https://codesandbox.io/s/materialuireactselect-6ufc2)
- [Validation (Yup, Zod, Joi, Superstruct)](https://codesandbox.io/s/schema-validations-uc1m6)
- [React Dropzone + Material UI](https://codesandbox.io/s/reactdropzone-materialuidropzone-yjb8w)
## How to Contribute
๐ Thanks for considering contributing!
Please read our [CONTRIBUTING.md](https://github.com/iusehooks/usetheform/blob/master/CONTRIBUTING.md) for guidelines.
## ๐ License
This project is licensed under the MIT License.
See the [LICENSE](./LICENSE.md) file for details.
