1 | # formsy-react
|
2 |
|
3 | [![GitHub release](https://img.shields.io/github/release/formsy/formsy-react.svg)](https://github.com/formsy/formsy-react/releases)
|
4 | ![CI](https://github.com/formsy/formsy-react/workflows/CI/badge.svg)
|
5 | [![Coverage Status](https://coveralls.io/repos/github/formsy/formsy-react/badge.svg?branch=master)](https://coveralls.io/github/formsy/formsy-react?branch=master)
|
6 | [![GitHub contributors](https://img.shields.io/github/contributors/formsy/formsy-react.svg)](https://github.com/formsy/formsy-react/contributors)
|
7 | ![Typescript Types included](https://badgen.net/npm/types/tslib)
|
8 |
|
9 | A form input builder and validator for React.
|
10 |
|
11 | | [Quick Start](#quick-start) | [API](/API.md) | [1.x API](https://github.com/formsy/formsy-react/blob/v1.x/API.md) |
|
12 | | --------------------------- | -------------- | ------------------------------------------------------------------ |
|
13 |
|
14 | ## Background
|
15 |
|
16 | [christianalfoni](https://github.com/christianalfoni/) wrote an article on forms and validation with React,
|
17 | [Nailing that validation with React JS](http://christianalfoni.github.io/javascript/2014/10/22/nailing-that-validation-with-reactjs.html),
|
18 | the result of that was this library.
|
19 |
|
20 | The main concept is that forms, inputs, and validation are done very differently across developers and projects. This
|
21 | React component aims to be that “sweet spot” between flexibility and reusability.
|
22 |
|
23 | This project was originally located at [christianalfoni/formsy-react](https://github.com/christianalfoni/formsy-react)
|
24 | if you're looking for old issues.
|
25 |
|
26 | ## What You Can Do
|
27 |
|
28 | 1. Build any kind of form element components. Not just traditional inputs, but anything you want, and get that
|
29 | validation for free
|
30 | 2. Add validation rules and use them with simple syntax
|
31 | 3. Use handlers for different states of your form. (`onSubmit`, `onValid`, etc.)
|
32 | 4. Pass external errors to the form to invalidate elements (E.g. a response from a server)
|
33 | 5. Dynamically add form elements to your form and they will register/unregister to the form
|
34 |
|
35 | ## Install
|
36 |
|
37 | `yarn add formsy-react react react-dom` and use with webpack, browserify, etc.
|
38 |
|
39 | ## Formsy component packages
|
40 |
|
41 | - [twisty/formsy-react-components](https://github.com/twisty/formsy-react-components) - Bootstrap components for a
|
42 | Formsy-React form.
|
43 | - [zabute/formsy-semantic-ui-react](https://github.com/zabute/formsy-semantic-ui-react) - Semantic-Ui-React components
|
44 | for a Formsy-React form.
|
45 |
|
46 | ## 1.x to 2.x Upgrade Guide
|
47 |
|
48 | The 2.0 release fixed a number of legacy decisions in the Formsy API, mostly a reliance on function props over value
|
49 | props passed down to wrapped components. However, the API changes are minor and listed below.
|
50 |
|
51 | - `getErrorMessage()` => `errorMessage`
|
52 | - `getErrorMessages()` => `errorMessages`
|
53 | - `getValue()` => `value`
|
54 | - `hasValue()` => `hasValue`
|
55 | - `isFormDisabled():` => `isFormDisabled`
|
56 | - `isFormSubmitted()` => `isFormSubmitted`
|
57 | - `isPristine()` => `isPristine`
|
58 | - `isRequired()` => `isRequired`
|
59 | - `isValid():` => `isValid`
|
60 | - `showError()` => `showError`
|
61 | - `showRequired()` => `showRequired`
|
62 |
|
63 | ## Quick Start
|
64 |
|
65 | ### 1. Build a Formsy element
|
66 |
|
67 | ```jsx
|
68 | // MyInput.js
|
69 | import { withFormsy } from 'formsy-react';
|
70 | import React from 'react';
|
71 |
|
72 | class MyInput extends React.Component {
|
73 | constructor(props) {
|
74 | super(props);
|
75 | this.changeValue = this.changeValue.bind(this);
|
76 | }
|
77 |
|
78 | changeValue(event) {
|
79 | // setValue() will set the value of the component, which in
|
80 | // turn will validate it and the rest of the form
|
81 | // Important: Don't skip this step. This pattern is required
|
82 | // for Formsy to work.
|
83 | this.props.setValue(event.currentTarget.value);
|
84 | }
|
85 |
|
86 | render() {
|
87 | // An error message is passed only if the component is invalid
|
88 | const errorMessage = this.props.errorMessage;
|
89 |
|
90 | return (
|
91 | <div>
|
92 | <input onChange={this.changeValue} type="text" value={this.props.value || ''} />
|
93 | <span>{errorMessage}</span>
|
94 | </div>
|
95 | );
|
96 | }
|
97 | }
|
98 |
|
99 | export default withFormsy(MyInput);
|
100 | ```
|
101 |
|
102 | `withFormsy` is a [Higher-Order Component](https://facebook.github.io/react/docs/higher-order-components.html) that
|
103 | exposes additional props to `MyInput`. See the [API](/API.md#withFormsy) documentation to view a complete list of the
|
104 | props.
|
105 |
|
106 | ### 2. Use your Formsy element
|
107 |
|
108 | ```jsx
|
109 | import Formsy from 'formsy-react';
|
110 | import React from 'react';
|
111 | import MyInput from './MyInput';
|
112 |
|
113 | export default class App extends React.Component {
|
114 | constructor(props) {
|
115 | super(props);
|
116 | this.disableButton = this.disableButton.bind(this);
|
117 | this.enableButton = this.enableButton.bind(this);
|
118 | this.state = { canSubmit: false };
|
119 | }
|
120 |
|
121 | disableButton() {
|
122 | this.setState({ canSubmit: false });
|
123 | }
|
124 |
|
125 | enableButton() {
|
126 | this.setState({ canSubmit: true });
|
127 | }
|
128 |
|
129 | submit(model) {
|
130 | fetch('http://example.com/', {
|
131 | method: 'post',
|
132 | body: JSON.stringify(model),
|
133 | });
|
134 | }
|
135 |
|
136 | render() {
|
137 | return (
|
138 | <Formsy onValidSubmit={this.submit} onValid={this.enableButton} onInvalid={this.disableButton}>
|
139 | <MyInput name="email" validations="isEmail" validationError="This is not a valid email" required />
|
140 | <button type="submit" disabled={!this.state.canSubmit}>
|
141 | Submit
|
142 | </button>
|
143 | </Formsy>
|
144 | );
|
145 | }
|
146 | }
|
147 | ```
|
148 |
|
149 | This code results in a form with a submit button that will run the `submit` method when the form is submitted with a
|
150 | valid email. The submit button is disabled as long as the input is empty ([required](/API.md#required)) and the value is
|
151 | not an email ([isEmail](/API.md#validators)). On validation error it will show the message: "This is not a valid email".
|
152 |
|
153 | ## 3. More
|
154 |
|
155 | See the [API](/API.md) for more information.
|
156 |
|
157 | ## Contribute
|
158 |
|
159 | - Fork repo
|
160 | - `yarn`
|
161 | - `yarn lint` runs lint checks
|
162 | - `yarn test` runs the tests
|
163 | - `npm run deploy` build and release formsy
|
164 |
|
165 | ## Changelog
|
166 |
|
167 | Check out our [Changelog](https://github.com/formsy/formsy-react/blob/master/CHANGELOG.md) and
|
168 | [releases](https://github.com/formsy/formsy-react/releases)
|
169 |
|
170 | ## License
|
171 |
|
172 | [The MIT License (MIT)](/LICENSE)
|