Formask

Formask is minimal form management abstract implemented by React. Provided with asynchronous validation, dynamic validation schema and work with native and third-party input field.

Install

npm i formask --save

Example

http://groupystinks.com/formask/

API

Props

defaultValues?: {[field: string]: any}

defaultValues defines initial value of each field. These initial values are stored in formask internal state and could be accessed through props.values either in render props (render: (props: FormaskProps) => ReactElement) or children if it's function (children: (props: FormaskProps) => ReactElement).

defaultErrors?: {[field: string]: { error?: any, valid: boolean}}

defaultErrors defines initial error of each field. Initial errors are stored in formask internal state and can be accessed through props.errors like defaultValue does.

defaultTouches?: {[field: string]: boolean}

defaultTouches defines initial touch of each field. Touch is stored in internal state to track each field's user interaction status, where true means already interacted. It can be accessed through props.touches like defaultValue does.

render?: (props: FormaskProps) => React.ReactElement

redner is a function to define Component will be rendered. render's first parameter is FormaskProps where all utility functions and internal state are passed in.

onSubmit?: (values: FormValues, formaskProps: FormaskProps ) => void

onSubmit is a function to be called while 'onsubmit' event is triggered. It will be passed in form FormValues and FormaskProps.

schema?: { [field: string]: { type: string; required?: boolean; [customrule: string]: (value) => Promise | boolean } }

schema defines validation rule of each form field. There's some examples in Example. Support Javascript native types including:

• String
• Number
• Date
• Boolean
• Array
• Array validation
• Nested object validation

required specify neccassary field. Formask will bypass field from validation if required is false.

customrule is used as customized validation function. return true means check pass, return false means check failed.

errorMessages?: { [field: string]: any }

errorMessages defines corresponding error message to schema. If error occur, message will be exposed in props.errors (see FormaskProps). It could be string, react element and whatever you may want when error occurs.

FormaskProps

FormaskProps is composed of internal state, methods and event handlers of Formask. It will be exposed in API like render, onSubmit and etc..

errors: { [field: string]: { error?: any, valid: boolean} }

errors specifies error message and valid status in each field.

values: { [field: string]: any }

values specifies value in each field.

touches: { [field: string]: boolean }

touches specifies touch status in each field. Normally, touch is set to true while user blur on input field. For those fields have no input, please see Custom Touch Field.

types: { [field: string]: string }

types specifies data type for each field if available. Formask will detect field data type from defaultValues, onChange event and etc..

isValid: boolean

isValid specifies validation status on form.

isSubmitting: boolean

isSubmitting turn true if form submit handler is triggered. Afterwards, setIsSubmitting is exposed to manipulate its status.

submitHandler: (e: React.FormEvent) => void

Event handlers of onsubmit event. Normally you would want to put it in form onsubmit attribute like:

  <form onSubmit={submitHandler}>
  ...

changeHandler: (e: React.ChangeEvent) => void

Event handlers of onchange event. It will hook input value into Formask's values. Normally you would wnat to use it while your field component is native input like:

  <input
    id="first"
    value={values.first}
    onChange={changeHandler}
    onBlur={blurHandler}
  />

blurHandler: (e: any) => void | ((e: any) => void)

Event handlers of onblur event. It will set Formask's touches once user on blur input. Like onChangeHanlder, we would like to use it in native input.

getFieldsValue: () => FormValues

Get FormValues.

hook: (id: string, options: { changeHandlerName: string, blurHandlerName: string }) => (ele: React.ReactElement<{}>) => React.ReactElement;

hook serve as a bridge to connect Formask and Widget. Widget is any React element you want to record its value into Formask's field. Under the hood, hook does few things you need to know:

• Set id
• Clone original Widget, add few props and pass on.
• Pass Formask's onChange/onBlur to Widget, by which user can "hook" their Widget into Formask. For more real use cases, you probably want to see Example.

setIsSubmitting: (isSubmitting: boolean) => void

Modify isSubmitting status.

reset: (options?: { type?: 'initial' | 'clean', fields?: Array }) => void

passing nothing If no parameters is passed in, Formask reset all fields to clean state.

options.type: reset literally means to clear all changes. By definition, there's two types of reset you can set in options.type:

1. clean(default) By passing 'clean' to type, Formask will clean all internal state into empty, including values, errors and etc..
2. initial By passing 'initial' to type, Formask will reset to default values previously set by defaultValues, defaultErrors and etc..

options.fields If options.fields is passed in, Formask will only reset specified fields according to what reset type is.

setTouches: (touches: FormTouches) => void

setTouches manipulate Formask touches. It let you can change touches on those non-input fields.

validate: (fields?: Array) => Promise

validate will check fields value against schema and return result in promise. It support asynchronous validation. By default, if no parameters is passed, it will go through all fields. Optionally, you can pass in fields to specify which to validate.

While submitHandler is triggered, validate will be executed.