@app-elements/form NPM

Form

Handle your Forms with React and global state!

Installation

npm install --save @app-elements/form

Usage

import Form from '@app-elements/form'
import { routeTo } from '@app-elements/router'

const TextInput = ({ ...props }) =>
  <input type='text' {...props} />

const Login = () => {
  const formProps = {
    name: 'LoginForm',
    action: 'auth/login',
    method: 'post',
    noAuth: true,
    initialData: {
      username: 'example'
    },
    onSuccess: ({ token, userId }) => {
      setState(
        { token, userId }
        () => routeTo('dashboard')
      )
    },
    onFailure: (err) => {
      console.log('onFailure', err)
      setState({
        notification: { status: 'failure', message: 'We were not able to log you in!' }
      })
    }
  }

  return (
    <Form {...formProps}>
      // Each form input requires a `name` prop. It will be the key set on the Form state.
      // In this case, the form name is `LoginForm`, so:
      //   {
      //     LoginForm: {
      //       email: '',
      //       username: '',
      //       password: ''
      //     }
      //   }
      <TextInput name='email' />
      <input isFormField name='username' />
      <TextInput name='password' />
      <button type='submit'>Login</button>
    </Form>
  )
}

export default Login

<Form /> will automatically iterate it's children and if any of them match a formFieldNames then it will automatically sync the data from that form input.

// These are the component names that we will sync values
// to our parent Form state.
let formFieldNames = [
  'InputText',
  'InputLocation',
  'TextInput',
  'TextArea',
  'Checkbox',
  'Select',
  'Radio',
  'Question',
  'DatePicker',
  'Slider'
]

You can also add additional field names:

import { addFieldNames } from '@app-elements/form'

addFieldNames('MyCoolField', 'NeatoField', 'BurritoField')

Or add isFormField attribute:

const MyCustomInput => <input isFormField name='hello' />

import { addFieldNames } from '@app-elements/form'

addFieldNames('MyCoolField', 'NeatoField', 'BurritoField')

In the future, we should probably just automatically sync all native web form elements (input, select, checkbox, textarea, etc.. 🤷‍♀️)

Difference between `onSubmit` and `action, method, noAuth, onSuccess, onFailure`

There are two main ways to use Form. The first is the more bare-bones onSubmit. When a user submits your form, if onSubmit was defined, it will be called with { hasError, errors, data, done } and you are left to determine what you want to do with the potential errors or form data.

The second way, is a convience around sending the form data to an API endpoint. You define the endpoint via action (named after native web form attribute) as well as the method. And you define the onSuccess and onFailure callbacks.

In both cases, any provided validations are run. With onSubmit any failed validations will be contained in the errors object. With the action way, the API request will not be made if there are any failed validations.

Props

Prop	Type	Default	Description
`name`	String	None	The name of the form. Will be used as the parent key in global state.
`initialData`	Object	None	An object to prefill the form with. Each key should correspond to the name of a field.
`validations`	Object	None	An object of field validations. Each key should match a field name and the value should be a function that accepts the current field value and return null if valid, or a string describing the error if invalid.
`action`	String	None	URL to send form data to when submitted
`method`	String	None	The HTTP method to use when sending data to the `action` URL
`noAuth`	Boolean	`false`	If the request should not include auth token in the headers
`onSuccess`	Function	None	The function to call if the request was successful, called with the JSON response from the server
`onFailure`	Function	None	The function to call if the request failed, called with the caught error
`onSubmit`	Function	None	If set, `{ action, method, noAuth, onSuccess, onFailure }` will be ignored. Instead, `onSubmit` will be called with `{ hasError, errors, data, done }` See below for more details

onSubmit Props

Prop	Type	Description
`hasError`	Boolean	Indicates if a validation error was found, offered as a convenience so you don't have to inspect `errors`
`errors`	Object	An object of any found errors. Each key will match the name of the offending field. The value will be the error.
`data`	Object	The form data! Each key is a name of a field, the value is the value given by the user.
`done`	Function	A function you can call to reset the form state. It has the signature `(errors = {}, values)`. You can pass in the existing errors, so they don't get reset. If `values` is null, then the `initialData` will be set again. If you wish to clear all values, pass an empty object: `done({}, {})`