1
1
mirror of https://github.com/theoludwig/react-component-form.git synced 2024-07-17 07:30:13 +02:00
react-component-form/README.md

146 lines
6.0 KiB
Markdown
Raw Normal View History

2020-08-04 16:22:31 +02:00
<h1 align="center">react-component-form</h1>
<p align="center">
<strong>Manage React Forms with ease.</strong>
</p>
<p align="center">
2023-12-26 22:24:32 +01:00
<a href="./CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="CONTRIBUTING /></a>
2020-12-27 19:47:15 +01:00
<a href="./LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue.svg" alt="Licence MIT"/></a>
2021-06-17 18:48:19 +02:00
<a href="./CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg" alt="Contributor Covenant" /></a>
<br />
2023-12-26 22:24:32 +01:00
<a href="https://github.com/theoludwig/react-component-form/actions/workflows/build.yml"><img src="https://github.com/theoludwig/react-component-form/actions/workflows/build.yml/badge.svg?branch=master" alt="Build" /></a>
<a href="https://github.com/theoludwig/react-component-form/actions/workflows/lint.yml"><img src="https://github.com/theoludwig/react-component-form/actions/workflows/lint.yml/badge.svg?branch=master" alt="Lint" /></a>
<a href="https://github.com/theoludwig/react-component-form/actions/workflows/test.yml"><img src="https://github.com/theoludwig/react-component-form/actions/workflows/test.yml/badge.svg?branch=master" alt="Test" /></a>
2021-06-17 18:48:19 +02:00
<br />
2020-12-27 19:47:15 +01:00
<a href="https://conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg" alt="Conventional Commits" /></a>
2021-06-17 19:32:56 +02:00
<a href="https://github.com/semantic-release/semantic-release"><img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="semantic-release" /></a>
2021-06-17 18:48:19 +02:00
<a href="https://www.npmjs.com/package/react-component-form"><img src="https://img.shields.io/npm/v/react-component-form.svg" alt="npm version"></a>
2020-08-04 16:22:31 +02:00
</p>
## 📜 About
2020-08-05 02:53:04 +02:00
**react-component-form** is a lightweight form component for [React.js](https://reactjs.org/), it allows you to get the inputs values without state thanks to `onChange` or `onSubmit` props.
2020-08-04 16:22:31 +02:00
2022-08-25 23:24:40 +02:00
There is also a [React Hooks](https://reactjs.org/docs/hooks-intro.html) to be used in combination with the `<Form />` component to validate the data with [Ajv JSON schema validator](https://ajv.js.org/), see [advanced usage](#%EF%B8%8F-advanced-usage).
2022-08-26 23:05:38 +02:00
Example demo: [https://react-component-form.vercel.app/](https://react-component-form.vercel.app/).
2020-08-04 16:49:14 +02:00
2020-08-04 16:22:31 +02:00
## 💾 Install
2020-10-03 19:07:09 +02:00
```sh
2020-08-04 16:22:31 +02:00
npm install --save react-component-form
```
2020-08-04 16:49:14 +02:00
## ⚙️ Usage
2020-08-04 16:22:31 +02:00
2022-10-03 21:23:17 +02:00
_Note: The examples use TypeScript, but obviously you can use JavaScript. Be aware that `HandleForm` is the type definition for the `onChange` and `onSubmit` props._
2022-08-25 23:24:40 +02:00
2020-08-04 16:22:31 +02:00
```tsx
import React from "react"
import { Form } from "react-component-form"
import type { HandleForm } from "react-component-form"
2020-08-04 16:22:31 +02:00
2022-08-26 00:30:54 +02:00
export const Example = () => {
2020-08-04 16:22:31 +02:00
const handleSubmit: HandleForm = (formData, formElement) => {
console.log(formData) // { inputName: 'value of the input' }
formElement.reset()
}
return (
<Form onSubmit={handleSubmit}>
<input type="text" name="inputName" />
<button type="submit">Submit</button>
2020-08-04 16:22:31 +02:00
</Form>
)
}
```
Basically you have access to the same props of the HTML `form` tag in React, but the `onSubmit` and the `onChange` props are differents.
2020-08-04 16:22:31 +02:00
2022-08-25 23:24:40 +02:00
Instead to get the `event` param you get `formData` and `formElement` parameters:
2020-08-04 16:22:31 +02:00
2022-08-26 23:05:38 +02:00
- `formData`: Object where the keys are the name of your inputs and the current value. Behind the scene, it uses the [FormData](https://developer.mozilla.org/docs/Web/API/FormData) constructor.
- `formElement`: The HTML form element in the DOM so for example you can access the `.reset()` method on a [HTMLFormElement](https://developer.mozilla.org/docs/Web/API/HTMLFormElement).
2020-08-04 16:22:31 +02:00
2022-08-25 23:24:40 +02:00
## ⚙️ Advanced Usage
This example shows how to use the `<Form />` component with `useForm` hook to validate the data with [Ajv JSON schema validator](https://ajv.js.org/).
You can see a more detailled example in the [./example](./example) folder.
```tsx
import React from "react"
import { Form, useForm } from "react-component-form"
import type { HandleUseFormCallback } from "react-component-form"
2022-08-25 23:24:40 +02:00
const schema = {
inputName: {
type: "string",
2022-08-25 23:24:40 +02:00
minLength: 3,
maxLength: 20,
},
2022-08-25 23:24:40 +02:00
}
2022-08-26 00:30:54 +02:00
export const Example = () => {
const { handleUseForm, errors, message } = useForm(schema)
2022-08-25 23:24:40 +02:00
2022-08-26 00:30:54 +02:00
const onSubmit: HandleUseFormCallback<typeof schema> = (
formData,
formElement,
2022-08-26 00:30:54 +02:00
) => {
console.log(formData) // { inputName: 'value of the input validated and type-safe' }
2022-08-25 23:24:40 +02:00
formElement.reset()
// The return can be either `null` or an object with a global message of type `'error' | 'success'`.
return {
type: "success",
message: "Success: Form submitted",
}
2022-08-25 23:24:40 +02:00
}
return (
2022-08-26 00:30:54 +02:00
<Form onSubmit={handleUseForm(onSubmit)}>
<input type="text" name="inputName" />
2022-08-25 23:24:40 +02:00
{errors.inputName != null && <p>{errors.inputName[0].message}</p>}
<button type="submit">Submit</button>
{message != null && <p>{message}</p>}
2022-08-25 23:24:40 +02:00
</Form>
)
}
```
## API
### `useForm(schema)`
#### Parameters
- `schema`: The JSON schema to validate the data (recommended to use [@sinclair/typebox](https://www.npmjs.com/package/@sinclair/typebox)).
#### Returns
2022-08-26 23:05:38 +02:00
- `handleUseForm(onSubmit)`: Function to be used with the `onSubmit` or `onChange` prop of the `<Form />` component.
- `fetchState = 'idle'`: The current state of the form (`'error' | 'success' | 'idle' | 'loading'`).
- `setFetchState`: Function to update the `fetchState`.
- `message`: Global message of the form (not specific to a property).
- `setMessage`: Function to update the `message`.
- `errors`: Object of errors:
- Key: correspond to a property in the JSON Schema.
- Value: array of [ajv `ErrorObject`](https://ajv.js.org/api.html#error-objects).
The array will always have at least one element (never empty) in case of errors.
If the value is `undefined`, it means there are no errors for this property.
## 💡 Contributing
Anyone can help to improve the project, submit a Feature Request, a bug report or
even correct a simple spelling mistake.
The steps to contribute can be found in [CONTRIBUTING.md](./CONTRIBUTING.md).
2020-08-04 16:22:31 +02:00
## 📄 License
[MIT](./LICENSE)