rc-form

React High Order Form Component.

Development

npm install
npm start

Example

http://localhost:8000/examples/

online example: http://react-component.github.io/form/examples/

Feature

support reactjs and even react-native

Install

Usage

import { createForm } from 'rc-form';

class Form extends React.Component {
  submit = () => {
    this.props.form.validateFields((error, value) => {
      console.log(error, value);
    });
  }

  render() {
    let errors;
    const { getFieldProps, getFieldError } = this.props.form;
    return (<div>
      <input {...getFieldProps('normal')}/>
      <input {...getFieldProps('required', {
        onChange(){}, // have to write original onChange here if you need
        rules: [{required: true}],
      })}/>
      {(errors = getFieldError('required')) ? errors.join(',') : null}
      <button onClick={this.submit}>submit</button>
    </div>)
  }
}

export createForm()(Form);

or a quicker version:

import { createForm } from 'rc-form';

class Form extends React.Component {
  componentWillMount() {
    this.requiredDecorator = this.props.form.getFieldDecorator({
        name: 'required',
        rules: [{required: true}],
    });
  },

  submit = () => {
    this.props.form.validateFields((error, value) => {
      console.log(error, value);
    });
  }

  render() {
    let errors;
    const { getFieldError } = this.props.form;
    return (<div>
      {this.requiredDecorator(
      <input onChange={
      // can still write your own onChange }
      />)}
      {(errors = getFieldError('required')) ? errors.join(',') : null}
      <button onClick={this.submit}>submit</button>
    </div>)
  }
}

export createForm()(Form);

createForm(formOption): Function

formOption.validateMessages: Object

preset messages of async-validator

formOption.mapProps: Function(props): Object

Get new props transfered to WrappedComponent. Defaults to props=>props.

formOption.onFieldsChange(props, fields)

Called when field changed, you can dispatch fields to redux store.

formOption.mapPropsToFields(props)

convert value from props to fields. used for read fields from redux store.

formOption.withRef: boolean

Maintain an ref for wrapped component instance, use refs.wrappedComponent to access.

createForm() will return another function:

function(WrappedComponent: React.Component): React.Component

Will pass a object as prop form with the following members to WrappedComponent:

getFieldProps(name, option): Object

Will create props which can be set on a input/InputComponent which support value and onChange interface.

After set, this will create a binding with this input.

<form>
  <input {...getFieldProps('name', { ...options })} />
</form>

name: String

This input's unique name.

option.exclusive: boolean

whether set value exclusively. used with radio.

option.valuePropName: String

Prop name of component's value field, eg: checkbox should be set to checked ...

option.getValueFromEvent

Specify how to get value from event. Defaults to

function (e) {
  if (!e || !e.target) {
    return e;
  }
  const { target } = e;
  return target.type === 'checkbox' ? target.checked : target.value;
}

option.getValueProps

get the component props according to field value. Defaults to

function (value) {
  return { value };
}

option.initialValue

Initial value of current component.

option.normalize(value, prevValue, allValues)

Return normalized value

option.trigger: String

Defaults to onChange. Event which is listened to collect form data.

option.validate: Object[]

option.validate[n].trigger: String|String[]

Event which is listened to validate. Defaults to onChange, set to falsy to only validate when call props.validateFields.

option.validate[n].rules: Object[]

Validator rules. see: async-validator

option.validateTrigger && option.rules

{
  validateTrigger: 'onBlur',
  rules: [{required: true}],
}
// is the shorthand of
{
  validate: [{
    trigger: 'onBlur',
    rules: [required: true],
  }],
}

option.validateFirst: Boolean

Defaults to false. whether stop validate on first rule of error for this field.

getFieldDecorator(name:String, option: Object): (React.Node): React.Node

Similar to getFieldProps, but add some helper warnings and you can write onXX directly inside React.Node props:

<form>
  {getFieldDecorator('name', otherOptions)(<input />)}
</form>

getFieldsValue([fieldNames: String[]])

Get fields value by fieldNames.

getFieldValue(fieldName: String)

Get field value by fieldName.

getFieldInstance(fieldName: String)

Get field react public instance by fieldName.

setFieldsValue(obj: Object)

Set fields value by kv object.

setFieldsInitialValue(obj: Object)

Set fields initialValue by kv object. use for reset and initial display/value.

setFields(obj: Object)

Set fields by kv object. each field can contain errors and value member.

validateFields([fieldNames: String[]], [options: Object], callback: Function(errors, values))

Validate and get fields value by fieldNames.

options is the same as validate method of async-validator. And add force and scroll. scroll is the same as dom-scroll-into-view's function parameter config.

options.force: Boolean

Defaults to false. Whether to validate fields which have been validated(caused by validateTrigger).

getFieldError(name): String[]

Get input's validate errors.

isFieldValidating(name: String): Bool

Whether this input is validating.

isFieldsValidating(names: String[]): Bool

Whether one of the inputs is validating.

isSubmitting(): Bool

Whether the form is submitting.

submit(callback: Function)

Cause isSubmitting to return true, after callback called, isSubmitting return false.

resetFields([names: String[]])

Reset specified inputs. Defaults to all.

rc-form/lib/createDOMForm(formOption): Function

createForm enhancement, support props.form.validateFieldsAndScroll

props.form.validateFieldsAndScroll([fieldNames: String[]], [options: Object], callback: Function(errors, values))

props.form.validateFields enhancement, support scroll to the first invalid form field

options.container: HTMLElement

Defaults to first scrollable container of form field(until document).

Notes

Do not use stateless function component inside Form component: facebook/react#6534
you can not set same prop name as the value of validateTrigger/trigger for getFieldProps

<input {...getFieldProps('change',{
  onChange: this.iWantToKnow // you must set onChange here or use getFieldDecorator to write inside <input>
})}>

you can not use ref prop for getFieldProps

<input {...getFieldProps('ref')} />

this.props.form.getFieldInstance('ref') // use this to get ref

<input {...getFieldProps('ref',{
  ref: this.saveRef // use function here or use getFieldDecorator to write inside <input> (only allow function)
})} />

Test Case

npm test
npm run chrome-test

Coverage

npm run coverage

open coverage/ dir

License

rc-form is released under the MIT license.

colorhook/form