Skip to content

Commit

Permalink
v7.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@erikras
erikras committed Nov 27, 2017
1 parent 8c6ec32 commit 532b6a2
Show file tree
Hide file tree
Showing 74 changed files with 13,622 additions and 8,320 deletions.
30 changes: 17 additions & 13 deletions README.md
View file
@@ -1,8 +1,10 @@
# redux-form

---

[<img src="http://npm.packagequality.com/badge/redux-form.png" align="right"/>](http://packagequality.com/#?package=redux-form)

[![NPM Version](https://img.shields.io/npm/v/redux-form.svg?style=flat)](https://www.npmjs.com/package/redux-form)
[![NPM Version](https://img.shields.io/npm/v/redux-form.svg?style=flat)](https://www.npmjs.com/package/redux-form)
[![NPM Downloads](https://img.shields.io/npm/dm/redux-form.svg?style=flat)](https://www.npmjs.com/package/redux-form)
[![Build Status](https://img.shields.io/travis/erikras/redux-form/v6.svg?style=flat)](https://travis-ci.org/erikras/redux-form)
[![codecov.io](https://codecov.io/gh/erikras/redux-form/branch/master/graph/badge.svg)](https://codecov.io/gh/erikras/redux-form)
Expand All @@ -12,25 +14,27 @@
[![Twitter URL](https://img.shields.io/twitter/url/https/github.com/erikras/redux-form.svg?style=social)](https://twitter.com/intent/tweet?text=With%20@ReduxForm,%20I%20can%20keep%20all%20my%20form%20state%20in%20Redux!%20Thanks,%20@erikras!)
[![Patreon](https://img.shields.io/badge/patreon-support%20the%20author-blue.svg)](https://www.patreon.com/erikras)

`redux-form` works with [React Redux](https://github.com/rackt/react-redux) to enable an html form in
[React](https://github.com/facebook/react) to use [Redux](https://github.com/rackt/redux) to store all of its state.
`redux-form` works with [React Redux](https://github.com/rackt/react-redux) to
enable an html form in [React](https://github.com/facebook/react) to use
[Redux](https://github.com/rackt/redux) to store all of its state.
[![Beerpay](https://beerpay.io/erikras/redux-form/badge.svg)](https://beerpay.io/erikras/redux-form)

<a href="https://app.codesponsor.io/link/P3WjkUw9LiYdiQBdHrtHZSSL/erikras/redux-form" rel="nofollow" target="_blank"><img src="https://app.codesponsor.io/embed/P3WjkUw9LiYdiQBdHrtHZSSL/erikras/redux-form.svg" style="width: 888px; height: 68px;" alt="Sponsor" /></a>

[<img src="https://raw.githubusercontent.com/erikras/redux-form/master/logo.png" align="right" class="logo" height="151" width="250"/>](http://erikras.github.io/redux-form/)

## Installation
```npm install --save redux-form```

`npm install --save redux-form`

## Documentation

* [Getting Started](https://redux-form.com/7.1.2/docs/GettingStarted.md/)
* [Examples](https://redux-form.com/7.1.2/examples/)
* [API](https://redux-form.com/7.1.2/docs/api/)
* [FAQ](https://redux-form.com/7.1.2/docs/faq/)
* [Getting Started](https://redux-form.com/7.2.0/docs/GettingStarted.md/)
* [Examples](https://redux-form.com/7.2.0/examples/)
* [API](https://redux-form.com/7.2.0/docs/api/)
* [FAQ](https://redux-form.com/7.2.0/docs/faq/)
* [Release Notes](https://github.com/erikras/redux-form/releases)
* [Older Documentation](https://redux-form.com/7.1.2/docs/DocumentationVersions.md/)
* [Older Documentation](https://redux-form.com/7.2.0/docs/DocumentationVersions.md/)

## 🏖 Code Sandboxes 🏖

Expand All @@ -52,9 +56,9 @@ You can play around with `redux-form` in these sandbox versions of the Examples.
## Videos

| [![A Practical Guide to Redux Form – React Alicante 2017](docs/ReactAlicante2017.gif)](https://youtu.be/ey7H8h4ERHg) |
| :--------------------------------------: |
| **A Practical Guide to Redux Form – React Alicante 2017** |
| :------------------------------------------------------------------------------------------------------------------: |
| **A Practical Guide to Redux Form – React Alicante 2017** |

| [![Abstracting Form State with Redux Form – JS Channel 2016](docs/JSChannel2016.gif)](https://youtu.be/eDTi7lYR1VU) |
| :--------------------------------------: |
| **Abstracting Form State with Redux Form – JS Channel 2016** |
| :-----------------------------------------------------------------------------------------------------------------: |
| **Abstracting Form State with Redux Form – JS Channel 2016** |
1 change: 1 addition & 0 deletions docs/DocumentationVersions.md
View file
@@ -1,5 +1,6 @@
# Documentation Versions

* [7.2.0](https://redux-form.com/7.2.0/)
* [7.1.2](https://redux-form.com/7.1.2/)
* [7.1.1](https://redux-form.com/7.1.1/)
* [7.1.0](https://redux-form.com/7.1.0/)
Expand Down
33 changes: 16 additions & 17 deletions docs/Flow.md
View file
@@ -1,14 +1,15 @@
# Flow Typing

`redux-form` supports static typing with [Flow](https://flow.org). Flow should automatically
import the types when you import the components and functions from `redux-form`. In addition,
you may import types for all the props provided by `redux-form` to your components.
`redux-form` supports static typing with [Flow](https://flow.org). Flow should
automatically import the types when you import the components and functions from
`redux-form`. In addition, you may import types for all the props provided by
`redux-form` to your components.

## Props Types

This will give you the types of the [`props`](http://redux-form.com/7.1.2/docs/api/Props.md/)
that will be injected into your decorated form component by the
`reduxForm()` higher order component.
This will give you the types of the
[`props`](http://redux-form.com/7.2.0/docs/api/Props.md/) that will be injected
into your decorated form component by the `reduxForm()` higher order component.

### `FormProps`

Expand All @@ -22,22 +23,19 @@ type Props = {

class MyForm extends React.Component {
props: Props

render() {
const { handleSubmit, someCustomThing } = this.props
return (
<form onSubmit={handleSubmit}>
// fields here
</form>
)
return <form onSubmit={handleSubmit}>// fields here</form>
}
}
```

### `FieldProps`

This will give you the shape of the props provided from
[`Field`](http://redux-form.com/7.1.2/docs/api/Field.md/) to your field component.
[`Field`](http://redux-form.com/7.2.0/docs/api/Field.md/) to your field
component.

```jsx
import type { FieldProps } from 'redux-form'
Expand All @@ -57,7 +55,8 @@ const renderField = ({ input, meta, ...rest } : FieldProps) =>
### `FieldsProps`

This will give you the shape of the props provided from
[`Fields`](http://redux-form.com/7.1.2/docs/api/Fields.md/) to your fields component.
[`Fields`](http://redux-form.com/7.2.0/docs/api/Fields.md/) to your fields
component.

```jsx
import type { FieldsProps } from 'redux-form'
Expand All @@ -81,8 +80,8 @@ const renderField = (fields : FieldsProps) =>
### `FieldArrayProps`

This will give you the shape of the props provided from
[`FieldArray`](http://redux-form.com/7.1.2/docs/api/FieldArray.md/) to your field array
component.
[`FieldArray`](http://redux-form.com/7.2.0/docs/api/FieldArray.md/) to your
field array component.

```jsx
import type { FieldArrayProps } from 'redux-form'
Expand All @@ -109,4 +108,4 @@ const renderFieldArray = ({ fields } : FieldArrayProps) =>
...

<FieldArray name="contacts" component={renderFieldArray}/>
```
```
110 changes: 69 additions & 41 deletions docs/GettingStarted.md
View file
@@ -1,48 +1,62 @@
# Getting Started With `redux-form`

The basic implementation of `redux-form` is simple. However, to make the most of it, it's recommended to have basic knowledge on:
The basic implementation of `redux-form` is simple. However, to make the most of
it, it's recommended to have basic knowledge on:

* [Redux](http://redux.js.org/) state container,
* [React](https://facebook.github.io/react/) and [Higher-Order Components (HOCs)](https://facebook.github.io/react/docs/higher-order-components.html).
* [React](https://facebook.github.io/react/) and
[Higher-Order Components (HOCs)](https://facebook.github.io/react/docs/higher-order-components.html).

## Overview

To connect your React form components to your Redux store you'll need following pieces from the `redux-form` package:
To connect your React form components to your Redux store you'll need following
pieces from the `redux-form` package:

* Redux Reducer: `formReducer`,
* React HOC `reduxForm()` and `<Field/>` component.

It's important to understand their responsibilities:

| | type | responsibility |
|---------------|-------------|----------------|
| `formReducer` | *reducer* | function that tells how to update the Redux store based on changes coming from the application; those changes are described by Redux actions |
| `reduxForm()` | *HOC* | function that takes configuration object and returns a new function; use it to wrap your `form` component and bind user interaction to dispatch of Redux actions |
| `<Field/>` | *component* | component that lives inside your wrapped `form` component; use it to connect the input components to the `redux-form` logic |
| | type | responsibility |
| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formReducer` | _reducer_ | function that tells how to update the Redux store based on changes coming from the application; those changes are described by Redux actions |
| `reduxForm()` | _HOC_ | function that takes configuration object and returns a new function; use it to wrap your `form` component and bind user interaction to dispatch of Redux actions |
| `<Field/>` | _component_ | component that lives inside your wrapped `form` component; use it to connect the input components to the `redux-form` logic |

## Data flow

The diagram below represents the simplified data flow. Note that in most cases you don't need to worry about the [action creators](http://redux-form.com/7.1.2/docs/api/ActionCreators.md/) for yourself, as they're already bound to dispatch for certain actions.
The diagram below represents the simplified data flow. Note that in most cases
you don't need to worry about the
[action creators](http://redux-form.com/7.2.0/docs/api/ActionCreators.md/) for
yourself, as they're already bound to dispatch for certain actions.

<div style="text-align: center;">
<img src="https://github.com/erikras/redux-form/raw/master/docs/reduxFormDiagram.png" width="500" style="max-width: 100%;"/>
</div>

Let's go through a simple example. We have a form component wrapped with `reduxForm()`. There is one text input inside, wrapped with `<Field/>`. The data flows like this:
Let's go through a simple example. We have a form component wrapped with
`reduxForm()`. There is one text input inside, wrapped with `<Field/>`. The data
flows like this:

1. User clicks on the input,
2. "Focus action" is dispatched,
3. `formReducer` updates the corresponding state slice,
4. The state is then passed back to the input.

Same goes for any other interaction like filling the input, changing its state or submitting the form.
Same goes for any other interaction like filling the input, changing its state
or submitting the form.

With `redux-form` comes a lot more: hooks for validation and formatting handlers, various properties and action creators. This guide describes the basic usage – feel free to dig deeper.
With `redux-form` comes a lot more: hooks for validation and formatting
handlers, various properties and action creators. This guide describes the basic
usage – feel free to dig deeper.

## Basic Usage Guide

### Step 1 of 4: Form reducer
### Step 1 of 4: Form reducer

The store should know how to handle actions coming from the form components. To enable this, we need to pass the `formReducer` to your store. It serves for **all of your form components**, so you only have to pass it once.
The store should know how to handle actions coming from the form components. To
enable this, we need to pass the `formReducer` to your store. It serves for
**all of your form components**, so you only have to pass it once.

```js
import { createStore, combineReducers } from 'redux'
Expand All @@ -60,36 +74,38 @@ const store = createStore(rootReducer)

Now your store knows how to handle actions coming from the form components.

**NOTE:** The key used to pass the `redux-form` reducer should be named **`form`**. If you need a custom key for some reason see [`getFormState` config](http://redux-form.com/7.1.2/docs/api/ReduxForm.md/#-getformstate-function-optional-) for more details.
**NOTE:** The key used to pass the `redux-form` reducer should be named
**`form`**. If you need a custom key for some reason see
[`getFormState` config](http://redux-form.com/7.2.0/docs/api/ReduxForm.md/#-getformstate-function-optional-)
for more details.

### Step 2 of 4: Form component

To make your form component communicate with the store, we need to wrap it with `reduxForm()`. It will provide the props about the form state and function to handle the submit process.
To make your form component communicate with the store, we need to wrap it with
`reduxForm()`. It will provide the props about the form state and function to
handle the submit process.

```js
import React from 'react'
import { Field, reduxForm } from 'redux-form'

let ContactForm = props => {
const { handleSubmit } = props
return (
<form onSubmit={ handleSubmit }>
{ /* form body*/ }
</form>
)
return <form onSubmit={handleSubmit}>{/* form body*/}</form>
}

ContactForm = reduxForm({
// a unique name for the form
form: 'contact'
})(ContactForm)

export default ContactForm;
export default ContactForm
```

Once we have the form component ready, it's time to add some inputs.

**NOTE**: If the `()()` syntax seems confusing, you can always break it down into two steps:
**NOTE**: If the `()()` syntax seems confusing, you can always break it down
into two steps:

```js
// ...
Expand All @@ -98,22 +114,28 @@ Once we have the form component ready, it's time to add some inputs.
createReduxForm = reduxForm({ form: 'contact' })

// evaluate it for ContactForm component
ContactForm = createReduxForm( ContactForm )
ContactForm = createReduxForm(ContactForm)

export default ContactForm;
export default ContactForm
```

### Step 3 of 4: Form `<Field/>` Components

The `<Field/>` component connects each input to the store. The basic usage goes as follows:
The `<Field/>` component connects each input to the store. The basic usage goes
as follows:

```js
<Field name="inputName" component="input" type="text" />
;<Field name="inputName" component="input" type="text" />
```

It creates an HTML `<input/>` element of type `text`. It also passes additional props such as `value`, `onChange`, `onBlur`, etc. Those are used to track and maintain the input state under the hood.
It creates an HTML `<input/>` element of type `text`. It also passes additional
props such as `value`, `onChange`, `onBlur`, etc. Those are used to track and
maintain the input state under the hood.

**NOTE**: `<Field/>` component is much more powerful. Apart from basic input types, it can take a class or a stateless component. When you're ready, go to the [docs](http://redux-form.com/7.1.2/docs/api/Field.md/#usage) to find out more.
**NOTE**: `<Field/>` component is much more powerful. Apart from basic input
types, it can take a class or a stateless component. When you're ready, go to
the [docs](http://redux-form.com/7.2.0/docs/api/Field.md/#usage) to find out
more.

Let's finish up our contact form:

Expand All @@ -124,7 +146,7 @@ import { Field, reduxForm } from 'redux-form'
let ContactForm = props => {
const { handleSubmit } = props
return (
<form onSubmit={ handleSubmit }>
<form onSubmit={handleSubmit}>
<div>
<label htmlFor="firstName">First Name</label>
<Field name="firstName" component="input" type="text" />
Expand All @@ -147,33 +169,39 @@ ContactForm = reduxForm({
form: 'contact'
})(ContactForm)

export default ContactForm;
export default ContactForm
```

From now on, the store should be populated based on actions coming from your form component. We can now handle the submission.
From now on, the store should be populated based on actions coming from your
form component. We can now handle the submission.

### Step 4 of 4: Reacting to submit

The submitted data is passed as JSON object to your `onSubmit` function. Let's `console.log` it out:
The submitted data is passed as JSON object to your `onSubmit` function. Let's
`console.log` it out:

```js
import React from 'react'
import ContactForm from './ContactForm'

class ContactPage extends React.Component {
submit = (values) => {
submit = values => {
// print the form values to the console
console.log(values)
}
render() {
return (
<ContactForm onSubmit={this.submit} />
)
return <ContactForm onSubmit={this.submit} />
}
}
```

You can now take it from here. We recommend to check out the [examples](http://redux-form.com/7.1.2/examples/). The common next steps could also be:
* setting the [initial form values](http://redux-form.com/7.1.2/examples/initializeFromState/),
* implementing the [validation](http://redux-form.com/7.1.2/examples/syncValidation/),
* creating dynamic forms with [arrays of fields](http://redux-form.com/7.1.2/examples/fieldArrays/).
You can now take it from here. We recommend to check out the
[examples](http://redux-form.com/7.2.0/examples/). The common next steps could
also be:

* setting the
[initial form values](http://redux-form.com/7.2.0/examples/initializeFromState/),
* implementing the
[validation](http://redux-form.com/7.2.0/examples/syncValidation/),
* creating dynamic forms with
[arrays of fields](http://redux-form.com/7.2.0/examples/fieldArrays/).

0 comments on commit 532b6a2

Please sign in to comment.