https://github.com/guilouro/formcat
A simple and easy way to control forms in React using the React Context API
https://github.com/guilouro/formcat
context context-api form react react-hooks
Last synced: 3 months ago
JSON representation
A simple and easy way to control forms in React using the React Context API
- Host: GitHub
- URL: https://github.com/guilouro/formcat
- Owner: guilouro
- License: mit
- Created: 2019-04-30T13:12:31.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T01:50:17.000Z (almost 3 years ago)
- Last Synced: 2025-03-20T08:18:47.392Z (8 months ago)
- Topics: context, context-api, form, react, react-hooks
- Language: JavaScript
- Homepage:
- Size: 3.07 MB
- Stars: 114
- Watchers: 5
- Forks: 5
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-components - formcat - A simple and easy way to control forms in React using the React Context API (Code Design / Form Logic)
- awesome-react-components - formcat - A simple and easy way to control forms in React using the React Context API (Code Design / Form Logic)
- awesome-react-components - formcat - A simple and easy way to control forms in React using the React Context API (Code Design / Form Logic)
README
A simple and easy way to control forms in React using the [React Context API](https://reactjs.org/docs/context.html)
[](https://codecov.io/gh/guilouro/formcat)
[](https://github.com/prettier/prettier)
## Getting Started
## Install
With npm
```
npm install --save formcat
```
With yarn
```
yarn add formcat
```
## How to use
First of all, we need to create a Field using the [HOC](https://facebook.github.io/react/docs/higher-order-components.html) `withContextForm` as the example below:
```js
/* InputField.js */
import { withContextForm } from 'formcat'
const InputField = ({ error, ...input }) => (
)
export default withContextForm(InputField)
```
Now we can use this component inside the Form:
```js
import { Form } from 'formcat'
import InputField from './InputField'
function Main () {
return (
)
}
```
# API
### Form
| Props | Type | Default value | Description |
| ----- | ---- | ------------- | ----------- |
| **keyUpValidation** | Boolean | `false` | When `true` the validations Field works with `keyUp` |
| **clearAfterSubmit** | Boolean | `false` | When `true` the form will be reset after submit |
| **onFormChange** | Function | `undefined` | A callback that returns an object with `name`, `type` and `value`
of the current change. |
| **onSubmit** | Function | `undefined` | A callback that returns an object with status and values. |
### Submit
For an easy `submit` process we can use the HOC `withSubmit` and create a Button that will be controlled by Form, or using the Submit component that already exists.
```js
// Creating
import { withSubmit } from 'formcat'
const Submit = withSubmit(props => )
//or
import { Submit } from 'formcat'
// Using
...
render (
...
Button Text
)
...
```
*Obs: This `button` will be enabled when Form is valid and disabled when is not valid*
### Custom Field
It's a field created with `withContextForm`.
| Props | Type | Default value | Description |
| ----- | ---- | ------------- | ----------- |
| **error** | Boolean | `false` | A flag that controls the field validation |
| **validations** | Array | `[]` | A list with functions validation |
| **required** | Boolean | `false` | Set required validation for this field |
| **defaultValue** | String | `""` | Set initial text value |
| **defaultChecked** | String | `""` | Set initial checked for field |
## Using validations
We can use many validations per field using the props `validations`. All we need to do is create a pure function that returns `true` or `false` following the example below:
```js
import { Form, withFormContext } from 'formcat'
const Field = withFormContext(({ error, ...input }) => (
))
const Main = () => {
// Validate if username is @guilouro
const usernameValidation = value => (
value === '@guilouro'
)
return (
)
}
```
A validation function has two params `value` and `state`:
```js
function validationName (value, state) {}
```
| Param | Type | Description |
| ----- | ---- | ------------- |
| **value** | String | Current field value |
| **state** | Object | An object with all fields value |
### Set values
We can set values out of Form using `Ref` and `updateFieldValue` as the example below:
| Param | Type | Description |
| ----- | ---- | ------------- |
| **name** | String | `null` | Field name |
| **text** | String | A new value for this field |
```js
import { Form, withFormContext } from 'formcat'
const Field = withFormContext(({ error, ...input }) => {}(
))
const Main = () => {
const form = useRef(null)
const setValue = () => {
form.current.updateFieldValue('username', '@guilouro')
}
return (
<>
Set @guilouro as value
>
)
}
```
## Fields we can use
There are some simple field created with `withContexForm` we can use in project or use as a reference for create a new custon field
### InputField
A simple `input` field
```js
import { InputField } from 'formcat/fields'
...
...
```
| Param | Type | Default value | Description |
| ----- | ---- | ------------- | --------------|
| **name** | String | `null` | Field name |
| **label** | String | `''` | A label for this field |
| **type** | String | `text` | A type for this input |
*Obs: And all common props*
### CheckboxField
A `input` `checkbox` field
```js
import { CheckboxField } from 'formcat/fields'
...
...
```
| Param | Type | Default value | Description |
| ----- | ---- | ------------- | --------------|
| **name** | String | `null` | Field name |
| **label** | String | `''` | A label for this field |
| **defaultChecked** | Boolean | `false` | A flag to define the initial status |
*Obs: And all common props*
### RadiosField
A simple `input` `radio` field
```js
import { RadiosField } from 'formcat/fields'
...
...
```
| Param | Type | Default value | Description |
| ----- | ---- | ------------- | --------------|
| **name** | String | `null` | Field name |
| **label** | String | `''` | A label for this field |
| **options** | Array | `[]` | A list of objects with `label`, `value` and `checked` |
*Obs: And all common props*
### SelectField
A simple `select` field
```js
import { SelectField } from 'formcat/fields'
...
...
```
| Param | Type | Default value | Description |
| ----- | ---- | ------------- | --------------|
| **name** | String | `null` | Field name |
| **label** | String | `''` | A label for this field |
| **options** | Array | `[]` | A list of objects with `label` and `value` |
*Obs: And all common props*
### TextField
A simple `textarea` field
```js
import { TextareaField } from 'formcat/fields'
...
...
```
| Param | Type | Default value | Description |
| ----- | ---- | ------------- | --------------|
| **name** | String | `null` | Field name |
| **label** | String | `''` | A label for this field |
*Obs: And all common props*
### Error styles
Invalid fields will receive a class: `className="formcat-error"`
## Examples
### Full form
A example with all fields, validation and a populate button
[](https://codesandbox.io/s/93465kmow?fontsize=14)
### Creating a custom fields
A example of the how create a custom field
[](https://codesandbox.io/s/3rpxomlm15?fontsize=14)
---
## Contributing
If you want to contribute with this component:
[Contributing Documentation](https://github.com/guilouro/formcat/blob/master/.github/CONTRIBUTING.md).