Form Component Reference¶

A group of one or more fields, inputs, lists, or other forms. A form results in a JavaScript object.

Usage¶

To use a Form type component, render it with nested children based on what you want the form to look like. The components within the form dictate the resulting data structure. Inputs typically result in scalar values, while Forms map to objects and FormLists map to arrays. Through nesting these various things you can create any schema. This usually works great, but if your design requires a different layout, you can always adjust the resulting object before validating or submitting it.

React JSX example:

import React, { Component } from 'react';
import { Form } from 'reacto-form';
import { Input } from 'reacto-form-inputs';
import mySubmissionFunction from './mySubmissionFunction';
import myValidationFunction from './myValidationFunction';

class SomePage extends Component {
  render() {
    return (
      <Form ref={i => { this.form = i; }} onSubmit={mySubmissionFunction} validator={myValidationFunction}>
        <Input name="firstName" type="text" />
        <Input name="lastName" type="text" />
        <button type="button" onClick={() => { this.form.submit(); }}>Submit</button>
      </Form>
    );
  }
}

There are typically only three things you need to do:

• Pass a validator function to the validator property
• Pass a submission function to the onSubmit property
• Call form.submit() on the form instance when you want to submit it

Properties¶

ALL properties are optional, but the name property is required on forms that are nested under other forms. The properties listed here are governed by the specification, but components are free to add any number of additional properties as necessary.

errors¶

PropTypes.arrayOf(PropTypes.shape({
  message: PropTypes.string.isRequired,
  name: PropTypes.string.isRequired,
}))

Array of error objects for all inputs on this form. It is usually not necessary to pass these errors yourself because the Form component will track them based on calls to validator, or they will be passed down by a parent Form or FormList. But you might want to pass them in directly when developing or testing.

name¶

PropTypes.string

If using a Form within another Form, set this to the desired object path where the value should be stored.

<Form>
  <Input name="nickname" type="text" />
  <Form name="address">
    ...
  </Form>
</Form>

onChanging¶

PropTypes.func

This function will be called as the form object changes, for example while a user is typing in one of the inputs. This is called more frequently than onChange but not necessarily on every single character change.

This may also be called on initial render to update default and hard coded input values.

onChange¶

PropTypes.func

This function will be called after the form object changes, whenever the user appears to be done changing one of the inputs, for example, after a user finishes typing and tabs off the field. This is called less frequently than onChanging.

This may also be called on initial render to update default and hard coded input values.

onSubmit¶

PropTypes.func

Provide a function that returns a Promise.

• If successfully submitted, return undefined, null, or { ok: true }.
• If submission failed, and you have additional validation errors that you want shown, return { ok: false, errors }, where errors is the standard errors array.
• If submission failed and you've already notified the user in the user interface, you can return { ok: false } or reject, whichever is most convenient.

When you return undefined, null, or { ok: true }, the Form component will reset all input values to match the values in the object in the Form's value property (by calling form.resetValue()).

value¶

PropTypes.obj

If the form is editing an existing object, provide it here. You can also provide an object with default values for a creation form. This is a basic JavaScript object which must match the structure of the object that the form component builds and passes to onChanging, onChange, and onSubmit.

validateOn¶

PropTypes.oneOf(['changing', 'changed', 'submit'])

This determines which event will run the validator function initially, after first mount or after resetValue has been called. The default is "submit". To skip validation, simply do not provide a validator function.

revalidateOn¶

PropTypes.oneOf(['changing', 'changed', 'submit'])

This determines how often the form will run the validator function after the initial validation is triggered based on validateOn, and until the form is reset by calling resetValue (which is also a side effect of a successful onSubmit call). The default is "changing". To skip validation, simply do not provide a validator function.

validator¶

PropTypes.func

If you want to use the built-in validation and error message handling, provide a validator function. This is a function that accepts a single argument that is the object to be validated and returns a Promise that resolves with a potentially empty errors array (see the errors property and validator spec).

hasBeenValidated¶

PropTypes.bool

This is set by parent forms when they are handling the validation for a child form.

Instance Properties¶

isDirty()¶

Returns a boolean indicating whether anything has been entered/changed by the user.

getValue()¶

Returns the current value of the form in state

validate()¶

Calls the validator function and then updates the errors tracked in state. Return a Promise that resolves with the errors array.

submit()¶

Calls this.validate() and then the onSubmit function.

resetValue()¶

Forces a reset of the value state to match the value prop, which also clears all validation errors.