├── .babelrc ├── .bookignore ├── .editorconfig ├── .eslintignore ├── .eslintrc ├── .github └── ISSUE_TEMPLATE.md ├── .gitignore ├── .npmignore ├── .travis.yml ├── LICENSE ├── README.md ├── SUMMARY.md ├── UPGRADE_GUIDE.md ├── book.json ├── contributing.json ├── docs ├── README.md ├── api │ ├── Control.md │ ├── Errors.md │ ├── Field.md │ ├── Fieldset.md │ ├── Form.md │ ├── actions.md │ ├── combineForms.md │ ├── createForms.md │ ├── formReducer.md │ ├── modelReducer.md │ └── utilities.md ├── guides │ ├── compare-redux-form.md │ ├── custom-controls.md │ ├── faqs.md │ ├── immutable.md │ ├── local.md │ ├── models.md │ ├── partial-models.md │ ├── quickstart.md │ ├── react-native.md │ ├── tracking.md │ └── validation.md └── recipes │ ├── quickstart.md │ ├── redux-form.md │ ├── simple-validation.md │ ├── simple.md │ └── sync-validation.md ├── esdoc.json ├── examples ├── builder │ ├── FormBuilder.js │ ├── app.js │ ├── index.html │ └── store.js ├── global.css ├── immutable-track │ ├── app.js │ └── index.html ├── immutable │ ├── app.js │ ├── components │ │ ├── submit-button.js │ │ └── user-form.js │ ├── index.html │ └── store.js ├── index.html ├── quick-start │ ├── app.js │ ├── components │ │ └── user-form.js │ ├── index.html │ └── store.js ├── server.js ├── stress-test │ ├── app.js │ ├── index.html │ └── store.js ├── validation │ ├── app.js │ ├── components │ │ ├── submit-button.js │ │ └── user-form.js │ ├── index.html │ └── store.js └── webpack.config.js ├── immutable.d.ts ├── immutable.js ├── native.js ├── package-lock.json ├── package.json ├── react-redux-form.d.ts ├── src ├── action-types.js ├── actions │ ├── batch-actions.js │ ├── field-actions.js │ ├── index.js │ └── model-actions.js ├── android.js ├── combineForms.js ├── components │ ├── control-component-factory.js │ ├── control-component.js │ ├── control-strip-defaults-component.js │ ├── errors-component.js │ ├── field-component.js │ ├── fieldset-component.js │ ├── form-component.js │ └── local-form-component.js ├── constants │ ├── control-props-map.js │ ├── initial-field-state.js │ ├── null-action.js │ └── validity-keys.js ├── enhancers │ ├── batched-enhancer.js │ └── modeled-enhancer.js ├── form │ ├── index.js │ ├── is-pending.js │ ├── is-pristine.js │ ├── is-retouched.js │ ├── is-touched.js │ └── is-valid.js ├── immutable.js ├── index.js ├── native.js ├── reducers │ ├── form-actions-reducer.js │ ├── form-reducer.js │ ├── form │ │ └── change-action-reducer.js │ ├── forms-reducer.js │ └── model-reducer.js └── utils │ ├── arrays-equal.js │ ├── assoc-in.js │ ├── capitalize.js │ ├── compose-reducers.js │ ├── contains-event.js │ ├── create-field.js │ ├── debounce.js │ ├── deep-compare-children.js │ ├── ends-with.js │ ├── find-key-immutable.js │ ├── find-key.js │ ├── find.js │ ├── flatten.js │ ├── get-field-form.js │ ├── get-field-from-state.js │ ├── get-field.js │ ├── get-form-value.js │ ├── get-form.js │ ├── get-from-immutable-state.js │ ├── get-model.js │ ├── get-validity.js │ ├── get-value.js │ ├── get.js │ ├── identity.js │ ├── inverse.js │ ├── invert-validators.js │ ├── invert-validity.js │ ├── is-multi.js │ ├── is-native.js │ ├── is-plain-object.js │ ├── is-validity-invalid.js │ ├── is-validity-valid.js │ ├── iteratee.js │ ├── map-values.js │ ├── map.js │ ├── merge-validity.js │ ├── merge.js │ ├── omit.js │ ├── partition.js │ ├── path-starts-with.js │ ├── persist-event-with-callback.js │ ├── pick.js │ ├── resolve-model.js │ ├── shallow-compare-without-children.js │ ├── shallow-equal.js │ ├── to-array.js │ ├── to-path.js │ ├── track.js │ ├── update-field.js │ ├── update-parent-forms.js │ └── update-sub-fields.js ├── test ├── action-types-spec.js ├── actions-spec.js ├── batched-actions-spec.js ├── combine-forms-spec.js ├── control-component-spec.js ├── control-strip-defaults-component-spec.js ├── custom-control-component-spec.js ├── errors-component-spec.js ├── field-actions-spec.js ├── field-component-spec.js ├── field-formatter-spec.js ├── field-parser-spec.js ├── form-component-spec.js ├── form-reducer-actions-spec.js ├── form-reducer-plugins-spec.js ├── form-reducer-spec.js ├── immutable-field-component-spec.js ├── immutable-model-reducer-spec.js ├── immutable-modeled-enhancer-spec.js ├── local-forms-spec.js ├── model-actions-spec.js ├── model-reducer-spec.js ├── model-resolving-spec.js ├── modeled-enhancer-spec.js ├── ref-spec.js ├── selectors-spec.js ├── spec-setup.js ├── tracking-spec.js ├── utils-spec.js └── utils.js ├── wallaby.config.js ├── webpack.config.base.js ├── webpack.config.prod.js └── yarn.lock /.babelrc: -------------------------------------------------------------------------------- 1 | { 2 | "plugins": [ 3 | "lodash", 4 | ["transform-react-remove-prop-types", {"mode": "wrap"}] 5 | ], 6 | "presets": ["es2015", "react", "stage-2"] 7 | } 8 | -------------------------------------------------------------------------------- /.bookignore: -------------------------------------------------------------------------------- 1 | src/ 2 | lib/ 3 | test/ 4 | examples/ 5 | home/ 6 | package.json 7 | webpack* 8 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # EditorConfig is awesome: http://EditorConfig.org 2 | 3 | # top-most EditorConfig file 4 | root = true 5 | 6 | # Unix-style newlines with a newline ending every file 7 | [*] 8 | end_of_line = lf 9 | insert_final_newline = true 10 | trim_trailing_whitespace = true 11 | charset = utf-8 12 | 13 | # Matches multiple files with brace expansion notation 14 | # Set default charset 15 | [*.{js}] 16 | charset = utf-8 17 | 18 | # Tab indentation (no size specified) 19 | [*.js] 20 | indent_style = space 21 | indent_size = 2 22 | 23 | # Matches the exact files either package.json or .travis.yml 24 | [{package.json,.travis.yml}] 25 | indent_style = space 26 | indent_size = 2 27 | 28 | [Makefile] 29 | indent_style = tab 30 | trim_trailing_whitespace = false 31 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | dist/ 2 | lib/ 3 | umd/ 4 | docs/ 5 | _book/ 6 | esdoc/ 7 | webpack.config.* 8 | wallaby.config.* 9 | examples/ 10 | home/ 11 | -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "airbnb", 3 | "parser": "babel-eslint", 4 | "env": { 5 | "node": true, 6 | "mocha": true 7 | }, 8 | "rules": { 9 | "new-cap": [ 10 | 2, { 11 | "capIsNewExceptions": ["List", "Map"] 12 | } 13 | ], 14 | "react/prefer-stateless-function": 0, 15 | "no-unused-vars": [ 16 | "error", 17 | { 18 | "varsIgnorePattern": "^_" 19 | } 20 | ], 21 | "no-confusing-arrow": [ 22 | "error", 23 | {"allowParens": true} 24 | ], 25 | "no-underscore-dangle": 0, 26 | "import/no-unresolved": 0 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | ### The Problem 2 | 3 | 4 | ### Steps to Reproduce 5 | 6 | 7 | ### Expected Behavior 8 | 9 | 10 | ### Actual Behavior 11 | 12 | 13 | ### Reproducible Code Example 14 | (please fork from [this CodePen template](http://codepen.io/davidkpiano/pen/yJwmEa) or [this CodeSandbox template](https://codesandbox.io/s/k3jyzwqo53)) 15 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | 5 | # Runtime data 6 | pids 7 | *.pid 8 | *.seed 9 | 10 | # Directory for instrumented libs generated by jscoverage/JSCover 11 | lib-cov 12 | 13 | # Coverage directory used by tools like istanbul 14 | coverage 15 | 16 | # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) 17 | .grunt 18 | 19 | # node-waf configuration 20 | .lock-wscript 21 | 22 | # Compiled binary addons (http://nodejs.org/api/addons.html) 23 | build/Release 24 | 25 | # Dependency directory 26 | # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git 27 | node_modules 28 | 29 | # Docs 30 | _book/ 31 | esdoc/ 32 | home/ 33 | 34 | # Distributed files 35 | dist/ 36 | 37 | # Build files 38 | lib/ 39 | umd/ 40 | 41 | # Analysis files 42 | stats.json 43 | 44 | # Examples 45 | examples/sandbox 46 | 47 | # Other 48 | .vscode/ 49 | .idea/ 50 | -------------------------------------------------------------------------------- /.npmignore: -------------------------------------------------------------------------------- 1 | # Docs 2 | _book/ 3 | docs/ 4 | dist/ 5 | 6 | # Misc 7 | node_modules/ 8 | .editorconfig 9 | .eslintignore 10 | .eslintrc 11 | .babelrc 12 | .gitignore 13 | .travis.yml 14 | wallaby.config.js 15 | stats.json 16 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: node_js 2 | 3 | node_js: 4 | - "7" 5 | - "stable" 6 | 7 | # before_install: 8 | # - npm config set ignore-scripts true 9 | 10 | script: 11 | - yarn test 12 | - yarn run lint 13 | - yarn run build 14 | - yarn run tsdef 15 | 16 | cache: yarn 17 | # cache: 18 | # directories: 19 | # - node_modules 20 | 21 | branches: 22 | except: 23 | - v1 24 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 David Khourshid 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # React Redux Form 2 | 3 | [![Join the chat at https://gitter.im/react-redux-form/Lobby](https://badges.gitter.im/react-redux-form/Lobby.svg)](https://gitter.im/react-redux-form/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 4 | [![Build Status](https://travis-ci.org/davidkpiano/react-redux-form.svg?branch=master)](https://travis-ci.org/davidkpiano/react-redux-form) 5 | [![npm version](https://badge.fury.io/js/react-redux-form.svg)](https://badge.fury.io/js/react-redux-form) 6 | [![CDNJS](https://img.shields.io/cdnjs/v/react-redux-form.svg)](https://cdnjs.com/libraries/react-redux-form) 7 | 8 | ### ⚠️ This project is in maintenance mode only. Please consider using [Formik](https://github.com/jaredpalmer/formik) instead. 9 | 10 | ## [Read the Documentation](https://davidkpiano.github.io/react-redux-form/docs.html) 11 | 12 | React Redux Form is a collection of reducer creators and action creators that make implementing even the most complex and custom forms with React and Redux simple and performant. 13 | 14 | `npm install react-redux-form@latest --save` 15 | 16 | ## Installation 17 | 18 | ```bash 19 | # Dependencies (you probably already have these) 20 | npm install react react-dom redux react-redux --save 21 | 22 | # version 1.x.x 23 | npm install react-redux-form@latest --save 24 | ``` 25 | 26 | ## Zero-Boilerplate `` 27 | 28 | If you want to get up and running with forms quickly without having to set up Redux, [just use Local Forms](http://davidkpiano.github.io/react-redux-form/docs/guides/local.html): 29 | 30 | ```js 31 | import React from 'react'; 32 | import { LocalForm, Control } from 'react-redux-form'; 33 | 34 | export default class MyApp extends React.Component { 35 | handleChange(values) { ... } 36 | handleUpdate(form) { ... } 37 | handleSubmit(values) { ... } 38 | render() { 39 | return ( 40 | this.handleUpdate(form)} 42 | onChange={(values) => this.handleChange(values)} 43 | onSubmit={(values) => this.handleSubmit(values)} 44 | > 45 | 46 | 47 | 48 | ); 49 | } 50 | } 51 | ``` 52 | 53 | That's all you need. Seriously. [Read the Documentation](http://davidkpiano.github.io/react-redux-form/docs/guides/local.html) for more information. 54 | 55 | **NOTE:** Please use `` with `react-redux` version 4.x.x or 5.x.x. 56 | 57 | ## Quick Start 58 | For more fine-grained control (such as using custom reducers, storing form state globally, dispatching actions, etc.), you'll want to set up a Redux store for your forms. 59 | 60 | Be sure to read the [step-by-step quick start guide](http://davidkpiano.github.io/react-redux-form/docs/guides/quickstart.html) in the documentation. 61 | 62 | ```jsx 63 | import React from 'react'; 64 | import { createStore } from 'redux'; 65 | import { Provider } from 'react-redux'; 66 | import { combineForms } from 'react-redux-form'; 67 | 68 | import MyForm from './components/my-form-component'; 69 | 70 | const initialUser = { name: '' }; 71 | 72 | const store = createStore(combineForms({ 73 | user: initialUser, 74 | })); 75 | 76 | class App extends React.Component { 77 | render() { 78 | return ( 79 | 80 | 81 | 82 | ); 83 | } 84 | } 85 | ``` 86 | 87 | ```jsx 88 | // ./components/my-form-component.js' 89 | import React from 'react'; 90 | import { connect } from 'react-redux'; 91 | import { Control, Form } from 'react-redux-form'; 92 | 93 | class MyForm extends React.Component { 94 | handleSubmit(val) { 95 | // Do anything you want with the form value 96 | console.log(val); 97 | } 98 | 99 | render() { 100 | return ( 101 |
this.handleSubmit(val)}> 102 | 103 | 104 | 105 | 106 | ); 107 | } 108 | } 109 | 110 | // No need to connect()! 111 | export default MyForm; 112 | ``` 113 | 114 | ## Posting Issues 115 | When posting an issue, please include a detailed description along with a relevant code sample. Attaching a failing test case with your issue will go a long way and is much appreciated. 116 | 117 | Feel free to [fork this CodePen](http://codepen.io/davidkpiano/pen/yJwmEa) or [this CodeSandbox](https://codesandbox.io/s/k3jyzwqo53) for quickly creating reproducible examples! 118 | -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | * [Introduction](README.md) 4 | * [Guides](docs/guides/README.md) 5 | * [Quick Start](docs/guides/quickstart.md) 6 | * [Models](docs/guides/models.md) 7 | * [Validation](docs/guides/validation.md) 8 | * [Tracking Collections](docs/guides/tracking.md) 9 | * [Custom Controls](docs/guides/custom-controls.md) 10 | * [React Native](docs/guides/react-native.md) 11 | * [Partial Models](docs/guides/partial-models.md) 12 | * [Compare to Redux-Form](docs/guides/compare-redux-form.md) 13 | * [Immutable.js](docs/guides/immutable.md) 14 | * [Local Forms](docs/guides/local.md) 15 | * [FAQs](docs/guides/faqs.md) 16 | * [API Reference](docs/api/README.md) 17 | * [Control component](docs/api/Control.md) 18 | * [Form component](docs/api/Form.md) 19 | * [Field component](docs/api/Field.md) 20 | * [Fieldset component](docs/api/Fieldset.md) 21 | * [Errors component](docs/api/Errors.md) 22 | * [modelReducer](docs/api/modelReducer.md) 23 | * [formReducer](docs/api/formReducer.md) 24 | * [combineForms](docs/api/combineForms.md) 25 | * [createForms](docs/api/createForms.md) 26 | * [action creators](docs/api/actions.md) 27 | * [Recipes and Examples](docs/recipes/README.md) 28 | * [Quick Start](docs/recipes/quickstart.md) 29 | * [Redux Form Examples](docs/recipes/redux-form.md) 30 | * [Simple Form](docs/recipes/simple.md) 31 | * [Sync Validation](docs/recipes/sync-validation.md) 32 | -------------------------------------------------------------------------------- /UPGRADE_GUIDE.md: -------------------------------------------------------------------------------- 1 | # React Redux Form Upgrade Guide 2 | 3 | ## v0.14.3 to v1.0.0 Beta 4 | 5 | ### Goals 6 | 7 | - **Simplicity** 8 | - **Performance** 9 | - **Flexibility** 10 | - **Features** 11 | 12 | ### Quick Start - v0.x to v1.3.0+ 13 | 14 | **Creating the store - version 0.x:** 15 | _Note:_ This way will still work in v1.0! 16 | ```js 17 | import { createStore, combineReducers, applyMiddleware } from 'redux'; 18 | import { modelReducer, formReducer } from 'react-redux-form'; 19 | 20 | const initialUserState = { 21 | firstName: '', 22 | lastName: '' 23 | }; 24 | 25 | const store = createStore(combineReducers({ 26 | user: modelReducer('user', initialUserState), 27 | userForm: formReducer('user', initialUserState) 28 | })); 29 | 30 | export default store; 31 | ``` 32 | 33 | **:new: Creating the store - version 1.x:** 34 | ```js 35 | import { createStore, applyMiddleware } from 'redux'; 36 | import { combineForms } from 'react-redux-form'; 37 | 38 | const initialUserState = { 39 | firstName: '', 40 | lastName: '' 41 | }; 42 | 43 | const store = createStore(combineForms({ 44 | user: initialUserState, 45 | })); 46 | 47 | export default store; 48 | ``` 49 | 50 | **Setting up the form - v0.x:** 51 | _Note:_ This way will still work in v1.0! 52 | 53 | ```js 54 | import { Field } from 'react-redux-form'; 55 | // ... 56 | 57 | 58 | 59 | 60 | 61 | ``` 62 | 63 | **Setting up the form - v1.x:** 64 | ```js 65 | import { Control } from 'react-redux-form'; 66 | // ... 67 | 68 |
69 | 70 | 71 |
72 | ``` 73 | 74 | ### Breaking Changes 75 | 76 | - For simplicity and performance, the form state structure has changed: 77 | 78 | ```diff 79 | // Assume this model shape for userForm: 80 | // { 81 | // user: { 82 | // name: 'John Doe', 83 | // address: { 84 | // city: 'Orlando', 85 | // state: 'FL', 86 | // }, 87 | // phones: [ 88 | // '5551234', 89 | // '5550000', 90 | // ], 91 | // }, 92 | // }; 93 | 94 | // Form state 95 | - user; 96 | + user.$form; 97 | 98 | // Field state 99 | - user.fields.name; 100 | + user.name; 101 | 102 | // Deep Field State 103 | - user.fields['phones.0'] 104 | + user.phones[0] 105 | 106 | - user.fields['address.city'] 107 | + user.address.city 108 | 109 | // Deep Form State 110 | - user.fields.address 111 | + user.address.$form 112 | 113 | - user.fields.phones 114 | + user.phones.$form 115 | ``` 116 | 117 | To summarize: 118 | - If accessing an object or an array (i.e., a _subForm_), the form state is in `model.path.$form`. 119 | - If accessing a plain field (e.g., a string, boolean, number, etc.), the field state is in `model.path`. 120 | 121 | **Batch Action Enhancements** 122 | - Batching a single action now dispatches that action, instead of unnecessarily wrapping it in a `batch()` action. 123 | 124 | **Field Action Enhancements** 125 | - 🆕 `actions.setValidating(model[, validating])` will change the field's `.validating` state to `validating` (or `true` if not provided). 126 | - This is useful for distinguishing between `.pending` (a form/subForm is being submitted) and `.validating` (a field is asynchronously being validated). 127 | - 🆕 Of course, there is a new `actionTypes.SET_VALIDATING` action type. 128 | - `actions.setSubmitFailed(model[, submitFailed])` now takes in a `submitFailed` parameter (defaults to `true`). 129 | -------------------------------------------------------------------------------- /book.json: -------------------------------------------------------------------------------- 1 | { 2 | "gitbook": "3.x.x", 3 | "title": "React Redux Form", 4 | "plugins": [ 5 | "-highlight", 6 | "-sharing", 7 | "-fontsettings", 8 | "github", 9 | "theme-rrf" 10 | ], 11 | "pluginsConfig": { 12 | "github": { 13 | "url": "https://github.com/davidkpiano/react-redux-form" 14 | } 15 | } 16 | } 17 | -------------------------------------------------------------------------------- /contributing.json: -------------------------------------------------------------------------------- 1 | { 2 | "commit": { 3 | "subject_cannot_be_empty": true, 4 | "subject_must_be_longer_than": 4, 5 | "subject_must_be_shorter_than": 101, 6 | "subject_lines_must_be_shorter_than": 51, 7 | "subject_must_be_single_line": true, 8 | "subject_must_be_in_tense": "imperative", 9 | "subject_must_start_with_case": "lower", 10 | "subject_must_not_end_with_dot": true, 11 | "body_lines_must_be_shorter_than": 73 12 | }, 13 | "pull_request": { 14 | "subject_cannot_be_empty": true, 15 | "subject_must_be_longer_than": 4, 16 | "subject_must_be_shorter_than": 101, 17 | "subject_must_be_in_tense": "imperative", 18 | "subject_must_start_with_case": "upper", 19 | "subject_must_not_end_with_dot": true, 20 | "body_cannot_be_empty": true, 21 | "body_must_include_verification_steps": true 22 | }, 23 | "issue": { 24 | "subject_cannot_be_empty": true, 25 | "subject_must_be_longer_than": 4, 26 | "subject_must_be_shorter_than": 101, 27 | "subject_must_be_in_tense": "imperative", 28 | "subject_must_start_with_case": "upper", 29 | "subject_must_not_end_with_dot": true, 30 | "body_cannot_be_empty": true, 31 | "body_must_include_reproduction_steps": true 32 | } 33 | } 34 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | -------------------------------------------------------------------------------- /docs/api/Errors.md: -------------------------------------------------------------------------------- 1 | # Errors Component 2 | 3 | ## `` 4 | 5 | The `` component provides a handy way of displaying form errors for a given `model`. 6 | 7 | ```jsx 8 | // in render... 9 | 14 | 15 | `${val} is not a valid email.`, 20 | }} 21 | /> 22 | ``` 23 | 24 | By default, `` will display a `
` with each error message wrapped in a `` as children: 25 | 26 | ```html 27 |
28 | foo@bar is not a valid email. 29 | 30 |
31 | ``` 32 | 33 | There are many configurable props that will let you control: 34 | - when error messages should be shown 35 | - custom error messages based on the model value 36 | - the wrapper component (default: `
`) 37 | - the message component (default: ``) 38 | 39 | # Prop Types 40 | 41 | ## `model="..."` (required) 42 | 43 | _(String | Function)_: the string representation of the model path to show the errors for that model. A tracking function may be provided, as well. 44 | 45 | ### Notes 46 | - If you want to display form-wide errors, just use the form model! For example, if you have a form-wide `passwordsMatch` validator on the `user` form, you can display an error message like so: 47 | 48 | ```jsx 49 | 55 | ``` 56 | 57 | ## `messages={{...}}` 58 | 59 | _(Object)_: a plain object mapping where: 60 | - the keys are error keys (such as `"required"`) 61 | - the values are either strings or functions. 62 | 63 | If the message value is a function, it will be called with the model value. 64 | 65 | ### Example 66 | 67 | ```jsx 68 | `${val} is not a valid email address.', 74 | }} 75 | /> 76 | ``` 77 | 78 | ### Notes 79 | - The `messages` prop is a great place to keep custom error messages that can vary based on the location in the UI, instead of hardcoding error messages in validation fuctions. 80 | - If a message is _not_ provided for an error key, the message will default to the key value in the control's `.errors` property. 81 | - This means if you're using `actions.setErrors` or the `errors={{...}}` prop in `` or `` to set error messages, they will automatically be shown in ``. 82 | 83 | ## `show={...}` 84 | 85 | _(Any)_: The `show` prop determines when error messages should be shown, based on the model's field state (determined by the form reducer). 86 | 87 | It can be a boolean, or a function, string, or object as a [Lodash iteratee](https://lodash.com/docs#iteratee). 88 | 89 | 90 | ### Examples 91 | - `show={true}` will always show the errors if they exist 92 | - `show={(field) => field.touched && !field.focus}` will show errors if the model's field is touched and not focused 93 | - `show={{touched: true, focus: false}}` is the same as above 94 | - `show="touched"` will show errors if the model's field is touched 95 | 96 | ### Notes 97 | - For the greatest amount of control, use `show` as a function. 98 | - Use `show` as a boolean if you want to calculate when an error should be shown based on external factors, such as form state. 99 | 100 | ## `wrapper={...}` 101 | 102 | _(String | Function | Element)_: The `wrapper` component, which is the component that wraps all errors, can be configured using this prop. Default: `"div"`. 103 | 104 | ### Examples 105 | - `wrapper="ul"` will wrap all errors in an `