https://github.com/aichbauer/react-form-package
A declarative form component with inbuilt validation and state management
https://github.com/aichbauer/react-form-package
context form form-validation forms react state-management validation
Last synced: 10 months ago
JSON representation
A declarative form component with inbuilt validation and state management
- Host: GitHub
- URL: https://github.com/aichbauer/react-form-package
- Owner: aichbauer
- License: mit
- Created: 2018-10-03T20:00:55.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-04-29T13:26:40.000Z (over 2 years ago)
- Last Synced: 2025-03-04T20:40:52.928Z (10 months ago)
- Topics: context, form, form-validation, forms, react, state-management, validation
- Language: JavaScript
- Homepage: https://aichbauer.github.io/react-form-package/
- Size: 6.44 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# react-form-package
[](https://www.npmjs.com/package/react-form-package)
[](https://travis-ci.org/aichbauer/react-form-package)
[](https://codecov.io/gh/aichbauer/react-form-package)
[](https://aichbauer.github.io/react-form-package)
> A declarative form component with inbuilt validation and state management
## Table of Contents
* [Documentation](https://aichbauer.github.io/react-form-package)
* [Installation](#installation)
* [Simple Form](#simple-form)
* [Components](#components)
* [Form](#form)
* [Button](#button)
* [Field](#field)
* [FieldWrapper](#fieldwrapper)
* [RadioGroup](#radiogroup)
* [Select](#select)
* [Form Validation](#form-validation)
* [State](#state)
* [State Manipulation](#state-manipulation)
* [Custom Error Messages](#custom-error-messages)
* [Show Errors on Button Click](#show-errors-on-button-click)
* [Feedback on Disabled Button](#feedback-on-disabled-button)
* [Styling](#styling)
* [Dynamic Fields](#dynamic-fields)
* [Dynamic Fields 2](#dynamic-fields-2)
* [Add new Fields onClick](#add-new-fields-onclick)
* [Add new Fields onChange](#add-new-fields-onchange)
* [Dynamic Fields 3](#dynamic-fields-3)
* [Bind Input Fields](#bind-input-fields)
* [Bind Input Fields 2](#bind-input-fields-2)
* [onFocus, onChange, onBlur](#onfocus-onchange-onblur)
* [Third Party Components](#third-party-components)
* [Autocomplete with Downshift](#autocomplete)
* [File Upload](#file-upload)
* [Why?](#why)
* [License](#license)
## Installation
```sh
$ npm i react-form-package -S
```
or
```sh
$ yarn add react-form-package
```
## Simple Form
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
There are five (six) different components within this package. The `` component is only here for edge cases, e.g. working with third party components. So for this simple example we stick to these five:
```jsx
import {
Button,
Field,
Form,
RadioGroup,
Select,
} from 'react-form-package';
```
If you are familiar with writing HTML forms than you are all set up. There are no complex data props or functions that you have to call before you can set up a form and validate its input like in most other libraries. Why should you care about writing the validations for your form yourself? An email, a date, a url, and so on, will always have the same structure. `react-form-package` will not only help you by your forms state management, it also will help you validating your forms correctly.
### Basic Usage
* Every ``, ``, ``, and `` component must have an **id property** and a **type property**
* `` components have `` childs which must have a **value property**
* `` components have `` childs which must have an **id property**, **type property**, and **name property**
* If you want the form to valitate inputs and show error messages simply add a **validate prop** on the `` component
In this example we use all components and types this library supports:
```jsx
const myForm = (props) => (
checkbox
textarea
date
datetime-local
email
number
tel
text
password
time
url
select
--- Choose an option ---
option 1
option 2
option 3
radio
radio 1
radio 2
radio 3
console.log(state)}>submit
);
```
## Components
For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package).
### Form
This component is a wrapper for all the other components in this library. This component handles the global state for the form itself.
#### Basic Usage
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
Render a table.
```jsx
import { Form } from 'react-form-package';
const myForm = (props) => (
{/*
here comes your form
mix HTML with other
components from this
library: e.g.
*/}
);
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
validate| Bool | false | |
validateOnClick| Bool | false | If you want to show the errors of a form on the click of the button |
input | Element | `` | |
checkbox | Element | `` | |
radio | Element | `` | |
radioContainer | Element | `
` | | The Element that wraps the radio elements.
button | Element | `` | |
select | Element | `` | |
textarea | Element | `` | |
error | Element | `` | |
### Button
This component has to be a child within the `` component. This component gets the state from the `` component and returns it on its onClick prop. If the `` component has the validate prop set, the button will be disabled as long as the form is valid.
#### Basic Usage
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
Render a `` with a `` component.
```jsx
import {
Form,
Button,
} from 'react-form-package';
const myForm = (props) => (
alert(JSON.stringify(state, null, 2))}
onMouseEnter={(e, state) => console.log(e, state)}
onMouseLeave={(e, state) => console.log(e, state)}
>
Click me to see the state of the form
);
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
id | String | true | |
type | String | true | | `submit`
onClick | Func | false | | returns the state of the form
onMouseEnter | Func | false | | returns the event and the state of the form
onMouseLeave | Func | false | | returns the event and the state of the form (does not work on `disabled` buttons)
rfpRole | String | false | | only needed for [dynamically added fields](#dynamic-field-2), either `addField` or `removeField`
fieldId | String | false | | only needed for [dynamically added fields](#dynamic-field-2) on a button with rfpRole `removeField` (the id of the field to remove)
field | Object | false | | only needed for [dynamically added fields](#dynamic-field-2) on a button with rfpRole `addField`. This object holds at least `id`, `type`, and may hold `min`, `max`, `required`, `match`, `sameAs`
### Field
This component has to be a child within the `` component. This component handles its own state and on any state change it will report it to the `` component which validates the whole form.
#### Basic Usage
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
Render a `` with an email `` and a `` component.
```jsx
import {
Form,
Field,
} from 'react-form-package';
const myForm = (props) => (
Email
);
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
id | String | true | |
type | String | true | | `checkbox`, `date`, `textarea`, `datetime-local`, `email`, `number`, `tel`, `text`, `password`, `time`, `url`, `file`
required | Bool | false | false |
min | String (digit or date (YYYY-MM-DD)) | false | | `text`, `textarea`, `password`: has to have at least `min` characters; `number`, `date`: has to be at least `min`
max | String (digit or date (YYYY-MM-DD)) | false | | `text`, `textarea`, `password`: has to have at least `min` characters; `number`, `date`: has to be at least `min`
match | RegEx | false | | the input value has to match the `regular expression`
sameAs | String | the input value has to have the same value as the input field with the id specified in `sameAs`
preOnChange | Func | false | | manipulate the state before its validated (see [State Manipulation](#state-manipulation))
errorMessage | String | false | | define your own custom error message for the input
onFocus | Func | false | | get access to the state of the form when the user focus on the input
onChange | Func | false | | get access to the state of the form when the user changes the input
onBlur | Func | false | | get access to the state of the form when the user blurs the input
dynamic | Bool | false | | only needed for [dynamically added fields](#dynamic-field-2)
field | Object | false | | only needed for [dynamically added fields](#dynamic-field-2). This object holds at least `id`, `type`, and may hold `min`, `max`, `required`
bintTo | String | false | | only needed for [binding input fields](#bind-input-fields). The id of the inpu you want to manipulate
bindToCallback | Func | false | | only needed for [binding input fields](#bind-input-fields). The callback to set the target's (`bindTo`) input value, which gets called `onChange`
### FieldWrapper
> This component is here for edge cases where you get the state from another component and you have to pass it to the `` component manually, e.g. third party components.
This component has to be a child within the `` component. This component exposes three additional props to its child component so that you are able to use third party components.
#### Basic Usage
```jsx
import {
Form,
FieldWrapper,
} from 'react-form-package';
```
Render a `` with an `` and a `` component.
Take a look into the [Third Party Components Section](#third-party-components) to see how you can use this component properly.
```jsx
{/*
Render a child component that gets access to
onFocus
onBlur
onChange
*/}
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>Submit
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
id | String | true | |
type | String | true | | `checkbox`, `date`, `textarea`, `datetime-local`, `email`, `number`, `tel`, `text`, `password`, `time`, `url`, `file`
required | Bool | false | false |
min | String (digit or date (YYYY-MM-DD)) | false | | `text`, `textarea`, `password`: has to have at least `min` characters; `number`, `date`: has to be at least `min`
max | String (digit or date (YYYY-MM-DD)) | false | | `text`, `textarea`, `password`: has to have at least `min` characters; `number`, `date`: has to be at least `min`
match | RegEx | false | | the input value has to match the `regular expression`
sameAs | String | the input value has to have the same value as the input field with the id specified in `sameAs`
preOnChange | Func | false | | manipulate the state before its validated (see [State Manipulation](#state-manipulation))
errorMessage | String | false | | define your own custom error message for the input
#### Props that get exposed to the child component
To see how you can use this properties take a look at [Third Party Components](#third-party-components)
Property | Type | Required | Default | Description
---|---|---|---|---
onFocus | Func | false | | pass your `value` to this function to update the state of the `` component
onChange | Func | false | | pass your `value` to this function to update the state of the `` component
onBlur | Func | false | | pass your `value` to this function to update the state of the `` component
meta | Object | false | | get access to the state of the `` component (see [State](#state))
### RadioGroup
This component has to be a child within the `` component. This component must have `` components with the type="radio" as children. These children components must have a name prop which has to match the parents id. The id of the children will be the value of the `` component when clicked.
#### Basic Usage
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
Render a `` with a `` component.
```jsx
import {
Form,
RadioGroup,
} from 'react-form-package';
const myForm = (props) => (
Choose an option
option 1
option 2
option 3
);
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
id | String | true | |
type | String | true | | `radio`
required | Bool | false | false |
preOnChange | Func | false | | manipulate the state before its validated (see [State Manipulation](#state-manipulation))
errorMessage | String | false | | define your own custom error message for the input
onFocus | Func | false | | get access to the state of the form when the user focus on the input
onChange | Func | false | | get access to the state of the form when the user changes the input
onBlur | Func | false | | get access to the state of the form when the user blurs the input
bintTo | String | false | | only needed for [binding input fields](#bind-input-fields). The id of the inpu you want to manipulate
bindToCallback | Func | false | | only needed for [binding input fields](#bind-input-fields). The callback to set the target's (`bindTo`) input value, which gets called `onChange`
### Select
This component has to be a child within the `` component. This component must have `` components with an value prop as children.
#### Basic Usage
> For more detailed information you can take a look at the [documentation](https://aichbauer.github.io/react-form-package)
Render a `` with a `` and a `` component.
```jsx
import {
Form,
Select,
} from 'react-form-package';
const myForm = (props) => (
Select an option
--- Select an option ---
option 1
option 2
option 3
);
```
#### Props
Property | Type | Required | Default | Description
---|---|---|---|---
id | String | true | |
type | String | true | | `select`
required | Bool | false | false |
preOnChange | Func | false | | manipulate the state before its validated (see [State Manipulation](#state-manipulation))
errorMessage | String | false | | define your own custom error message for the input
onFocus | Func | false | | get access to the state of the form when the user focus on the input
onChange | Func | false | | get access to the state of the form when the user changes the input
onBlur | Func | false | | get access to the state of the form when the user blurs the input
bintTo | String | false | | only needed for [binding input fields](#bind-input-fields). The id of the inpu you want to manipulate
bindToCallback | Func | false | | only needed for [binding input fields](#bind-input-fields). The callback to set the target's (`bindTo`) input value, which gets called `onChange`
## Form Validation
Almost any form needs validation in some way. Fortunatly `react-form-package` comes with an declarative inbuild validation system.
What does decalrative mean in that way?
### Basic Example
If you want that your input field only allows valid emails you can add the type `email` to the `` component. If you also set `validate` property on the `` component the button only allowes to submit if the form is completely valid.
In the next example you are able to submit the form if the input is empty (because this field is not required) and if the input value is set to a valid email, but not if the input value is not a valid email.
```jsx
Email
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
If you add the property `required` to the `` component, everything stays the same except that you are not able to submit the form if the input value is empty.
```jsx
Email
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
### Type validation
A `` component can have diffferent `type` properties.
Additionally to the validation, if the browser supports HTML5 input types the input fields will be displayed as them, only allowing numbers by default if the type is set to `number`, etc. If the browser does not support HTML5 it will automatically uses a text input that keeps the validation. If the user inputs a non numeric character in a `number` input it will display the the error message and you cannot submit the form.
Type| Description
---|---
`checkbox` | `no` additional validation
`date` | validates if the input value matches the format `YYYY-MM-DD`
`textarea` | `no` additional validation
`datetime-local` | validates if the input value matches the format `YYYY-MM-DDTHH:MM`
`email` | validates if the input value matches the `standard email format`
`number` | validates if the input value matches a `valid number`
`tel` | validates if the input value matches the `standard phone number format`
`text` | `no` additional validation
`password` | `no` additional validation
`time` | validates if the input value matches the format `HH:MM`
`url` | validates if the input value matches the `standard url format`
`file` | `no` additional validation
### Additional rules
If you are using a `` component you can also add some additional rules for the validation.
`required` will work on all components, the ``, the ``, and the ``
Property | Type | Description
---|---|---
`required` | Bool | validates if the `input value is not empty`
`min` | String (digit or date (YYYY-MM-DD)) | `text`, `textarea`, `password`: validates if the input value is at least `min characters long`; `number`, `date`: validates if the input value is at least `min`
`max` | String (digit or date (YYYY-MM-DD)) | `text`, `textarea`, `password`: validates if the input value is maximum `max characters long`; `number`, `date`: validates if the input value is maximum `max`
`match` | Regex | validates if the input value matches the `regular expression`
`sameAs` | String | validates if the input of this field has the same value as the field specified in `sameAs`
`validate` | Func | a function that gets access to the value of the field `(value) => // write your own validation` (do not forget to write your own errorMessage)
Example with the `required`, `min`, `max`, `validate`, and `sameAs` properties:
```jsx
Text required, min, max
Number required, min, max
Text is required and has to validate the `validate` function (value === 'react')
value === 'react'} errorMessage={'This field is required\\nThis field has to match "react"'} required />
Date required, min, max
Password has to be the same as password 2
Password 2 has to be the same as password
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
Example with the match property:
```jsx
Text required and has to match "react"
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
This is just a simple example, off course you are able to pass any regular expression you would like. If you would like to customize the error messages take a look at [custom error messages](#custom-error-messages)
## State
> Working with the state data and meta data
A simple Example of how your Form could look like:
```jsx
this.handleOnClick(state)}
>
Submit
```
> You can also use `onFocus`, `onChange`, and `onBlur` on every `Field`, `Select`, or `RadioGroup` components to get access to the state of the form ([more info](#onfocus-onchange-onblur))
As you can see the `` component has a `onClick` property. This property takes a function. The `handleOnClick` function could look something like:
```js
async handleOnClick(state) {
// do something with the state
// e.g. send data to a server
try {
const response = await fetch('https://server.com/login', {
method: 'POST',
headers: {
'Content-Type': 'application/json; charset=utf-8',
},
body: JSON.stringify(state.data);
});
// do something with the response
} catch(error) {
// do something with the error
}
}
```
As you can see the `state` parameter is an object. It has three different properties.
* **data**: `object`
* **meta**: `object`
* **formValid**: `boolean`
In our case `data` would hold:
```js
{
"data": {
"email": "",
"password": ""
}
}
```
`meta` would hold:
```js
{
"meta": {
"email": {
"initialValue": "",
"dirty": false,
"pristine": true,
"visited": false,
"touched": false,
"value": "",
"valid": false,
"invalid": true,
"rules": {
"type": "email",
"min": undefined,
"max": undefined,
"sameAs": undefined,
"match": undefined,
"required": true,
}
},
"password": {
"initialValue": "",
"dirty": false,
"pristine": true,
"visited": false,
"touched": false,
"value": "",
"valid": false,
"invalid": true,
"rules": {
"type": "password",
"min": undefined,
"max": undefined,
"sameAs": undefined,
"match": undefined,
"required": true,
}
}
}
}
```
`formValid` would hold:
```js
{
"formValid": false
}
```
### Meta Description
Meta data gives you an overview of what happened on that field. E.g. if a field is `pristine` you could deside to not send its data to the server since, nothing changed.
Property | Type | Description
---|---|---
initialValue | `String` or `Bool` |
dirty | `Bool` | `true` if the `value !== initialValue`
pristine | `Bool` | `true` if the `value === initialValue`
visited | `Bool` | `true` if this field was focused (`onFocus`)
touched | `Bool` | `true` if this field was blurred (`onBlur`)
value | `String` or `Bool` |
valid | `Bool` | `true` if this field is valid (passed all rules)
invalid | `Bool` | `true` if this field is invalid (failed at least one rules)
rules | `object` | the rules for the validation of this field
rules.type | `String` | `checkbox`, `date`, `textarea`, `datetime-local`, `email`, `number`, `tel`, `text`, `password`, `time`, `url`, `radio`, `select`
rules.min | `Number` or `String` (YYYY-MM-DD) | `text`, `textarea`, `password`: this field has to have at least `min` characters; `number`, `date`: this field has to be at least `min`
rules.max | `Number` or `String` (YYYY-MM-DD) | `text`, `textarea`, `password`: this field has to have maximum `max` characters; `number`, `date`: this field has to be maximum `max`
rules.match | `RegEx` | thie fields has to match the regular expression
rules.sameAs | `String` | thie fields has to have the same value as the field with id `sameAs` (e.g. password fields)
rules.required | `Bool` | this field is required (has to have a value)
## State Manipulation
> How to manipulate the state before it is validated
Sometimes you need to manipulate the value of a input. It is not recommended, but there are some edge cases and situations where this comes in handy, e.g. you have an input and you have to ensure that the user capitalizes the first letter, e.g. on names.
For this use cases there is a property called `preOnChange`. This property takes a function that returns the new value of the input. You can only manipulate the value of the current input field.
The next example manipulates the input value that it always capitalizes the first letter of every word in the input field.
```jsx
Name:
autocapitalize(value, 'words')}
required
/>
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
## Custom Error Messages
If you want to display your own error messages, use the `errorMessage` property on the ``, ``, or `` component.
```jsx
Email
```
## Show Errors on Button Click
If you want to display the the erros on the button click you need to add the prop `validateOnClick` to the form.
When using the prop `validateOnClick` the state is also returned in the `onClick` function. You can check with
`state.formValid` if the data is valid and here you can start your request or whatever you need todo with the information.
```jsx
Email
{
if (state.formValid) {
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}
// do something else if form data is not valid
}}>
Submit
```
## Feedback on Disabled Button
Sometimes it is necessary to show an informal error message to the user when is hovering on a disabled button (which means the form is not valid yet).
For this example we use a popover for our disabled button that gives the user a hint what should be filled.
First import all the components that we need. We use [styled-bootstrap-components](https://aichbauer.github.io/styled-bootstrap-components) for our popup. You could also use a toast or something similar to indicate the user what fields are open.
```js
import {
Form,
Field,
Button,
} from 'react-form-package';
import {
Popover,
PopoverArrow,
PopoverBody,
PopoverHeader,
} from 'styled-bootstrap-component';
```
Next we make use of the buttons `onMouseEnter` function (unfortunatly the `onMouseLeave` function does not work on disabled buttons so we can not use it to hide the popover), and a `setTimeout` to hide the popover.
```js
class PopoverHint extends React.Component {
constructor(props) {
super(props);
this.state = {
top: 0,
left: 0,
hidden: true,
notValidFields: '',
};
this.handlePopover = this.handlePopover.bind(this);
}
handlePopover(ev, state) {
const { hidden } = this.state;
let notValidFields = Object.entries(state.meta).map((entry) => {
if (!entry[1].valid) {
return entry[0];
}
});
notValidFields = notValidFields.filter((i) => i !== undefined);
if (!state.formValid) {
this.setState({
top: ev.target.offsetTop - ev.target.offsetHeight,
left: ev.target.offsetLeft + ev.target.offsetWidth,
hidden: !hidden,
notValidFields: notValidFields.join(),
}, () => {
const { hidden: h } = this.state;
setTimeout(() => this.setState({
hidden: !h,
}), 1500);
});
}
}
render() {
const {
top,
left,
hidden,
notValidFields,
} = this.state;
return (
}
button={}
>
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
onMouseEnter={(e, state) => this.handlePopover(e, state)}
>
Hover button to show which fields are not valid
You need to fill out this fields
{notValidFields}
);
}
}
export { PopoverHint };
```
Now we render the `` and see the result.
```js
```
## Styling
To style this form you have three different options, all requires to pass a React component to a form prop.
### CSS-in-JS
> In this section we will use a library that uses `styled-components` to style our form
First you have to import the this library and the Form Components you want to use for your styling. In this example we will use [styled-bootstrap-components](https://aichbauer.github.io/styled-bootstrap-components).
```jsx
import {
Form,
Field,
Button,
} from 'react-form-package';
import {
Label,
FormGroup,
FormControl,
Column,
Button as Btn,
} from 'styled-bootstrap-components';
```
The next step is to create you form and pass the styled components as props to the `` component
```jsx
}
button={}
>
Email
console.log(state)} primary>Submit
```
### style prop
> In this section we will use a the `style` prop to style our form
To style your form pass components to the `` component that are styled with the style tag. When you create your own ``, `` components do not forget do bind functions like `onClick`, `onChange`, `onFocus`, `onBlur`. This functions are needed to make `react-form-package` work properly.
```jsx
const MyButton = (props) => (
{props.children}
);
const MyInput = (props) => (
);
```
The next step is to simply create you form and pass the styled components as props to the `` component
```jsx
}
input={}
>
Email
console.log(state)}>Submit
```
### CSS and className
> In this section we will use a the `className` prop and a css file to style our form
To style your form pass components to the `` component that have `className` prop and use css files (make sure to have an appropriate loader for your bundler).
```css
.button {
background: #001f3f;
border: 1px solid black;
padding: 8px 24px;
border-radius: 3px;
color: white;
cursor: pointer;
}
.input {
margin: 10px 0px;
padding: 8px 3px;
border: 1px solid #001f3f;
border-radius: 5px;
}
```
Import your `CSS file` to your application and make sure you have a loader for css.
```jsx
import './style.css';
const MyClassNameButton = (props) => (
{children}
);
const MyClassNameInput = (props) => (
);
```
The next step is to create you form and pass the styled components as props to the `` component.
```jsx
}
input={}
>
Email
console.log(state)}>Submit
```
### Passing props
To actually make your own components working with `react-form-package` you have to pass some props.
#### components
* The `Prop` is the prop on the `` component.
* `HTML` is the actual HTML element to use.
* `Props` are the props you have to pass these components e.g. `id={prop.id} or id={this.prop.id}` or `onChange={prop.onChange} or onChange={this.prop.onChange}`.
* `Info` shows you which props you have to bind.
Prop | HTML | Props | Info
---|--- | --- | ---
input | input | `id`, `type`, `onChange`, `onBlur`, `onFocus` |
checkbox | input | `id`,`type`, `onChange`, `onBlur`, `onFocus` |
radio | div | `id`,`type`, `onChange`, `onBlur`, `onFocus`, `children` | this is a wrapper that renders every child, and watch out for `` and handles their state
button | input | `id`, `type`, `onClick`, `children` |
select | select | `id`, `type`, `onChange`, `onBlur`, `onFocus`, `children` | this is a wrapper that renders every child, and watch out for `` and handles their state
textarea | textarea | `id`, `type`, `onChange`, `onBlur`, `onFocus` |
A `textarea` example:
```jsx
const myTextarea = (props) => (
);
```
## Dynamic Fields
Sometimes you need to create your `Form` out of dynamic data, e.g. from data you received from a server. This is mostly the case when using `checkboxes`, `radio groups`, or `select fields`.
For example: you could receive the data from the server and than use `setState` to set the data for your `checkboxes`, `radio groups`, and `select fields` used in your `` component.
```js
async componentDidMount() {
const response = await getDataFromServer();
this.setState({
checkboxData: response.data.checkboxData,
selectData: response.data.selectData,
radioData: response.data.radioData,
});
}
```
Than in your render function you would return something like:
```jsx
{checkboxData.map((checkbox) => (
{checkbox.name}
))}
--- Select an option ---
{selectData.map((selectOption) => (
{selectOption.name}
))}
{radioData.map((radioOption) => (
{radioOption.name}
))}
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}>
Submit
```
## Dynamic Fields 2
Sometimes you do not know how many fields your form should have, so you need a way to add dynamic fields on user events, e.g. on a button click if a user should decide if a new field is needed, or on a change of a field, e.g. when a field is filled a new field should appear.
### Add new Fields onClick
First off, import your components.
```js
import React from 'react';
import {
Form,
Field,
Button,
} from 'react-form-package';
```
The next step is to create a `class` that will render our form.
The state is allways handled by `react-form-package`, the only thing that you need todo is to handle the appearence of the form, e.g. add or remove the input.
We need create a `addField`, `removeField`, and optionally a `calculateAvailableId` function. The `calculateAvailableId` is only nessacary if you work on non unique index-based ids so that you ensure you do not overide an existing id.
The `addField` function is here to add a new Field when you click on a `` component.
To update the state of the `` component, you need to add a `rfpRole` property and a `field` or a `fieldId` property to a `` component.
The `rfpRole` takes a string which is either `addField` or `removeField`.
If you use the `` component to add a new field to the state of the form component you need to provide a `field` property which takes an object that represents your new `` component. This object has to have at least a `id` and a `type`, but you can extend this object with rules like: `min`, `max`, `required`, `match`, and `sameAs`.
If you use the `` component to add remove an existing field from the state of the form component you need to provide a `fieldId` property which takes a string: the `id` of the field you want to remove.
In the state of the `DynamicFields` component you have to create an array where you add refrences to the fields of your dynamic `` components. To add new fields you need to add a new refrence, so that the part of the DOM rerenders with the new Field Component. To remove the Fields not only from the state of the `` component but also from the DOM, you need to remove the refrences in your state that the component rerenders that part of the DOM.
```jsx
class DynamicFields extends React.Component {
constructor(props) {
super(props);
this.state = {
// the field refrences that we use to render in our component
companies: [
{
id: 'company-0',
},
],
};
this.addField = this.addField.bind(this);
this.removeField = this.removeField.bind(this);
this.calculateAvailableId = this.calculateAvailableId.bind(this);
}
calculateAvailableId() {
const {
companies,
} = this.state;
const arr = companies.map((item) => parseInt(item.id.split('-')[1], 10));
let currentHighestId = Math.max(...arr);
currentHighestId = currentHighestId !== -Infinity ? currentHighestId : 0;
const highestAvailableId = currentHighestId + 1;
return highestAvailableId;
}
addField() {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
// add a new field refrence to the component
this.setState({
companies: companies.concat({ id: `company-${highestAvailableId}` }),
});
}
removeField(idx) {
const {
companies,
} = this.state;
// remove a field refrence to the component
this.setState({
companies: companies.filter((_, index) => idx !== index),
});
}
render() {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
return (
{/* render the components based on our field refrences */}
{companies.map((company, idx) => (
component
fieldId={company.id}
onClick={() => this.removeField(idx)}
>
Remove Company
))}
component
field={{
id: `company-${highestAvailableId}`,
type: 'text',
required: true,
}}
onClick={() => this.addField()}
>
Add Company
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
submit
);
}
}
export { DynamicFields };
```
Now render this Component. Everytime you click on the button `Add Company` you get a new field, and everytime you click on the button `Remove Company` you remove the corresponding field.
### Add new Fields onChange
First off, import your components.
```js
import React from 'react';
import {
Form,
Field,
Button,
} from 'react-form-package';
```
The next step is to create a `class` that will render our form.
Everything stays the same as in the example above, except:
That we now use a `dynamic` property and the `field` property on the `` component. the `field` property takes the same properties as in the `` component. The `dynamic` property indicates that this `` component is dynamic and adds a new field in the state of the `` component when this `` is filled.
```jsx
class DynamicFields extends React.Component {
constructor(props) {
super(props);
// the field refrences that we use to render in our component
this.state = {
companies: [
{
id: 'company-0',
},
],
};
this.addField = this.addField.bind(this);
this.removeField = this.removeField.bind(this);
this.calculateAvailableId = this.calculateAvailableId.bind(this);
}
calculateAvailableId() {
const {
companies,
} = this.state;
const arr = companies.map((item) => parseInt(item.id.split('-')[1], 10));
let currentHighestId = Math.max(...arr);
currentHighestId = currentHighestId !== -Infinity ? currentHighestId : 0;
const highestAvailableId = currentHighestId + 1;
return highestAvailableId;
}
addField(state, id) {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
// add a new field refrence to the component
if (state.data[id] && parseInt(id.split('-')[1], 10) + 1 === highestAvailableId) {
this.setState({
companies: companies.concat({ id: `company-${highestAvailableId}` }),
});
}
}
removeField(idx) {
const {
companies,
} = this.state;
// remove a field refrence to the component
this.setState({
companies: companies.filter((_, index) => idx !== index),
});
}
render() {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
return (
{/* render the components based on our field refrences */}
{companies.map((company, idx) => (
component
field={{
id: `company-${highestAvailableId}`,
type: 'text',
required: true,
}}
onChange={(state) => this.addField(state, company.id)}
/>
{companies.length && (
component
fieldId={company.id}
onClick={() => this.removeField(idx)}
>
Remove Company
)}
))}
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
submit
);
}
}
export { DynamicFieldsOnChange };
```
Now render this Component. Everytime you fill out the `` component you will add a new ``, and everytime you click on the button `Remove Company` you remove the corresponding field.
## Dynamic Fields 3
When you have a part of your form that consists of multiple fields that needs to be dynamic, e.g. `streetname` and `housenumber`. >ou can add multiple fields to the state of the `` component by simle passing an array of objects to the `field` property instead of a single object. The same way you can remove multiple fields from state of the `` component, by passing an array of strings to the `fieldId` property instead of a single string.
### Add multiple dynamic fields to the state
First off, import your components.
```js
import React from 'react';
import {
Form,
Field,
Button,
} from 'react-form-package';
```
Now create your component:
```jsx
class MultipleDynamicFields extends React.Component {
constructor(props) {
super(props);
this.state = {
companies: [
{
id: 'street-0',
},
],
};
this.addField = this.addField.bind(this);
this.removeField = this.removeField.bind(this);
this.calculateAvailableId = this.calculateAvailableId.bind(this);
}
calculateAvailableId() {
const {
companies,
} = this.state;
const arr = companies.map((item) => parseInt(item.id.split('-')[1], 10));
let currentHighestId = Math.max(...arr);
currentHighestId = currentHighestId !== -Infinity ? currentHighestId : 0;
const highestAvailableId = currentHighestId + 1;
return highestAvailableId;
}
addField() {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
this.setState({
companies: companies.concat({ id: `street-${highestAvailableId}` }),
});
}
removeField(idx) {
const {
companies,
} = this.state;
this.setState({
companies: companies.filter((_, index) => idx !== index),
});
}
render() {
const {
companies,
} = this.state;
const highestAvailableId = this.calculateAvailableId();
return (
{companies.map((street, idx) => (
this.removeField(idx)}
>
Remove Company
))}
this.addField()}
>
Add Company Field
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
submit
);
}
}
export { MultipleDynamicFields };
```
Now lets render this component and see how you can add and remove multiple fields.
## Bind Input Fields
Sometimes a input value depends on another input value, e.g. the use inputs a range of house numbers and you have to calculate the dependend household count. So that the user is able to skip some fields but is also able to chnage the value if the user knows it better.
### Bind an input value to another input value
To handle such cases there are two properties available on the ``, the ``, and the `` component.
Property | Type | Required | Default | Description
---|---|---|---|---
bindTo | String, Array | false | | the `id`/`ids` of the field/fields you want to manipulate
bindToCallback | Func | false | | the callback to set the target's (`bindTo`) input value, which gets called `onChange`
#### Basic Usage
In our example we bind our first `housenumbers` input to the second `households` input. As long as the bound input field (`bindTo`, in our example the households field) is untouched (not blurred) the `binToCallback` will be executed `onChange` of the field where we have the `bindTo` and `bindToCallback` properties. The `bindToCallback` expects a String as return value, and gets the input value of the current input field `housenumbers`.
```jsx
House numbers:
{
const numbers = value.includes('-')
? value.split('-')
: value;
if (!Array.isArray(numbers)) {
return '1';
}
const number1 = parseInt(numbers[0]);
const number2 = parseInt(numbers[1]);
if (!number2 || number2 === number1) {
return '1';
}
if (number2 < number1) {
return '0';
}
const households = (number2 - number1 + 1).toString();
return households;
}
}
/>
Households:
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
## Bind Input Fields 2
Sometimes it is not enough to bind the the value of an input field to just one single different input field. So you can also pass an array of ids to the `bindTo` prop. As we learned in the [Bind Input Fields](#bind-input-fields) chapter, the `bindToCallback` is only triggered when the input field to which it is bound was not touched (blurred) yet. This sometimes has a problematic effect, e.g. if you have a select input to choose a email template, but everytime the user switches the select option, the template should be switched, even if the user touched one of the fields it was bound to. This can be achieved if you set a property called `bindToAlways`. If you return a single value from the `bindToCallback` every bound field will be populated with this value. If you want to have different values for each binding thn you can return an array of values. The binding will be in the same order as the order of the `bindTo` array. If the length of the array of the return value of the `bindToCallback` does not match the length of the `bindTo` ids, only the fields with an return value will be populated.
### Bind an input value to another input value
To handle such cases there are two properties available on the ``, the ``, and the `` component.
Property | Type | Required | Default | Description
---|---|---|---|---
bindTo | String, Array | false | | the `id`/`ids` of the field/fields you want to manipulate
bintToAllways | Bool | false | | only needed if you want that the bindToCallback is triggered even the bound input field was already touched (blurred)
bindToCallback | Func | false | | the callback to set the target's (`bindTo`) input value, which gets called `onChange`
### Basic Usage
In our example we use `Select` input to choose between different email templates.
```js
Email Template:
{
if(value === 'friends') {
return [
'What\'s up?', // subject as it appears first in the `bindTo` prop
'Just take a look at this meme...', // body as it appears second in the `bindTo` prop
];
}
return [
'Weekly report',
'Dear Boss,\n\n...\n...\n...',
];
}}
>
--- Select an email template ---
Friends
Boss
Subject:
Body:
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
## onFocus, onChange, onBlur
> get access to the state everytime the user interacts with your form
Sometimes, access to the forms state is needed even before the user submits the form. This can be if you want to store the forms state on the server on every change (e.g. every time the user changes a input or everytime the user blurs an input) or you want to check if the users input is already taken (e.g. a user might not be allowed to use a email or a username that is already taken and you want to give the user a fast respond before the user even submits the form).
You are not able to modify the state on this callbacks since `react-form-package` takes care of the state management, but you can use the state to communicate with a server or change the UI corresponding to the current state. If you have an edge case where you have to modify the state of the input use `preOnChange` (see [State Manipulation](#state-manipulation)).
### onFocus
```jsx
import {
Form,
Field,
} from 'react-form-package';
```
Render a `` with an email `` component and a `onFocus` property.
```jsx
{/* do something with the state onFocus */}
console.log(state)}
/>
```
### onChange
```jsx
import {
Form,
Field,
} from 'react-form-package';
```
Render a `` with an email `` component and a `onChange` property.
```jsx
{/* do something with the state onChange */}
console.log(state)}
/>
```
### onBlur
```jsx
import {
Form,
Field,
} from 'react-form-package';
```
Render a `` with an email `` component and a `onBlur` property.
```jsx
{/* do something with the state onBlur */}
console.log(state)}
/>
```
## Third Party Components
> Working with third party components
Sometimes you need to work with third party components to make something work properly, e.g. you need an autocompletion. This `react-form-package` does not provide an autocompletion by default, but luckily you can use third party components within `react-form-package` and keep all the functionality.
To give you an example of how to create a autocompletion form we use [downshift](https://github.com/paypal/downshift#readme).
`react-form-package` has a `` component. This component exposes four props to the child component: `onFocus`, `onBlur`, `onChange` and `meta`.
This props are functions that takes exactly one argument: `value`. Which should be a `string` for input fields or a `boolean` for a checkbox.
## Autocomplete
First off, import your components.
```js
import React from 'react';
import Downshift from 'downshift';
import {
FormControl,
Label,
} from 'styled-bootstrap-components';
```
The next step is to create a `Autocomplete` component.
We use the standard example from the [downshift](https://github.com/paypal/downshift#readme) documentation.
We use the exposed function props to change the state of the ``. Take a look at the `onChange` function of the `` component, or the `onFocus` and `onBlur` function on the input component, or the `meta` data used on the `` component.
```jsx
// ./Autocomplete.js
const items = [
{ value: 'apple' },
{ value: 'pear' },
{ value: 'orange' },
{ value: 'grape' },
{ value: 'banana' },
];
const Autocomplete = (props) => (
props.onChange(item.value)}
itemToString={(item) => (item ? item.value : '')}
>
{({
getInputProps,
getItemProps,
getLabelProps,
getMenuProps,
isOpen,
inputValue,
highlightedIndex,
selectedItem,
}) => (
Enter a fruit:
props.onFocus(e.target.value),
onBlur: (e) => props.onBlur(e.target.value),
placeholder: 'apple',
})}
// here we are using the meta data
valid={props.meta.touched ? props.meta.valid : undefined}
invalid={props.meta.touched ? props.meta.invalid : undefined}
/>
{isOpen
? items
.filter((item) => !inputValue || item.value.includes(inputValue))
.map((item, index) => (
-
{item.value}
))
: null}
)}
);
export { Autocomplete };
```
Now we have to import all components that we need and use our `` component inside the `` component.
```js
import React from 'react';
import { Autocomplete } from './Autocomplete';
import {
Form,
FieldWrapper,
Button,
} from 'react-form-package';
```
If you visit the focus and blur the input now there will be a error message, telling you that this field is required. If you type something and select a fruit from the autocompletion you will be able to submit the form. If the field was touched and the field is invalid it will use a red border, if the field was touched and the field is valid it will use a green border.
```jsx
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
## File Upload
Sometimes you need to upload files with your form, e.g. if you want to upload a profile picture for a user.
Use a `` with the type `file` and you will get the `FileList` object back as value in the `data` object.
```jsx
{
alert(JSON.stringify(state, null, 2));
alert('open the console to see the whole state...');
console.log(state);
}}
>
Submit
```
## Why?
> TL;DR: I wanted a form with inbuilt validation and state management that a developer can use only by knowing HTML
Forms! A pain in the ass for a user when they are not well developed. Mostly because developing forms is a pain in the ass too.
Why is developing good forms not easy?
Because
* of a lot of communication between the user and the program
* there are a lot of changes in the state of a program
* of the validation of the user input
I wanted a form that a developer can use only by knowing HTML. Most frontend developers know how a valid HTML form looks like on first sight but no frontend developer knows how a JavaScript library works when its been used for the first time. That is the reason why `react-form-package` was created. By using `react-form-package` you create a similar structure to a valid HTML form. Thats it. Input validation, form state management, and user communication is all handled by `react-form-package`.
### Why not use formik or react-final-form
Most of the `form libraries` I found were using `render props` or `higher order components`, which is not a ideal set up for a form because when the forms are getting more complex the more confusing the code will get. A form should be declarative, and what is more declartive than a plain HTML form? Not a `render prop hell` or `higher order confusion`. Also I did not find any library that came with an inbuilt validation system. Why do you need this? You should not consider writing your own validations if an email is always validated the same way, or the structure of a url is always the same. Writing your validations yourself can mislead you to produce duplicate code and this could lead to more bugs. What is also important: being flexible with styling. This is also not always easy with libararies. `react-form-package` only brings the logic and you choose how to style it. `CSS-in-JS`, `CSS`, or the `style prop`, it is up to you.
## License
MIT © Lukas Aichbauer