formo
Form state management
Usage (basic example)
import formo from 'formo' const MyFormoComponent =
Motivation and guiding principles
- avoid repeating common tasks among different form, such as validation logic, computing "dirtiness" state, enabling submit button, showing errors only if X, etc.
- it should be independent from rendering (not tied to a specific set of UI components)
- it should be independent from the state management framework (not tied to redux, mobx, etc.)
- it should be easy to use as-is, as a stateful component, and easy to integrate with any state management framework
API
Create a "formo component"
Component // ... MyComponent
From this component, you'll have access to the complete form state via props. This includes current values, validity, and other useful meta info such as "touched", "changed", etc. See a comprehensive list in the tables below.
configure a "formo component"
A "formo component" can be configured through props with a set of fields and validations to apply.
import MyFormoComponent from './MyFormoComponent' // ... { // `validations` and `onChange` are optional return <MyFormoComponent = = = /> } // ...
props
API
name | required | type | description |
---|---|---|---|
fields | required | dict(FieldName, Field) |
Configure form fields |
validations | dict(FieldNameOrForm, dict(validationName, Validations)) |
Optionally configure form-level and field-level validations | |
onChange | function<Value> |
Optionally provide an onChange callback, will be called with the new values after every change |
FieldName
: a string representing a field, e.g. "email".
Field
: an object in the form:
value: any initialValue: any active: ?boolean touched: ?boolean}
FieldNameOrForm = FieldName | 'form'
: form-level validations are specified using the special string "form".
Validations
: a dict(string, function)
with each function, returning a Boolean.
Each function is called with two arguments (field value
and all form values
) if applied to a field, with a single value (all form values
) if it is applied at form-level.
In other words, a validation function should be treated like a test that the field or the form should pass.
formo
will list the failed validation
function names in the validationErrors
array.
Validity for single fields and for the global form is computed based on presence (absence) of these errors.
fields
example
fields = email: value: cookieemail password: {} repeatPassword: {} foo: initialValue: true bar: initialValue: false
validations
example
validations = password: valuelength > 8 value repeatPassword: repeatPassword === password form: !valuefoo && !valuebar
Use form values from a "formo component"
Formo component props api
A formo component receives via props:
- form-level values and derived properties, via the
form
prop - for each field, field-level value and derived properties, via the
[field]
prop.
Form-level props
type | name/usage | description |
---|---|---|
function |
form.clearValues() |
Sets every field value in the form to field.initialValue || undefined . The input below should be aware and handle undefined as controlled anyway. |
function |
form.touchAll() |
Sets every field as "touched". Useful if we have a validation UI rendering logic similar to touched && errors && renderErrors() and we want to force errors rendering after a certain event (e.g. user clicks on "submit") |
boolean |
form.isChanged |
Is any field changed? |
boolean |
form.isValid |
Is the form as a whole "valid" (no validation errors)? |
list(string) |
form.validationErrors |
validations failing |
Form-level prop usage example
// ... { const submitEnabled = thispropsformisValid && thispropsformisChanged; const errors = return // ... errors <input ='submit' ='Submit' = /> // ... }// ...
Field-level props
type | name/usage | description |
---|---|---|
any |
[field].value |
Always == value || initialValue || undefined . The input below should be aware and handle undefined as controlled anyway |
any |
[field].initialValue |
initialValue provided in form config for the field, if any |
function(any) |
[field].update(newValue) |
Updates a field value. Typically passed to an input onChange |
boolean |
[field].active |
Whether the field is currently "active". It is guaranteed to be exclusive (a single field is active at any time. If multiple fields are marked as "active" in config, only the first one is considered active) |
function |
[field].setActive() |
Set the field as "active" |
function |
[field].unsetActive() |
Set the field as "non active". Also updates touched accordingly |
boolean |
[field].touched |
true if input has been unsetActive() in the past (typically after a blur, or, as always, if the field is configured as touched=true in config) |
function |
[field].clear() |
Set field value to initialValue || undefined |
boolean |
[field].isChanged |
true if input value is the same as initialValue (or "adequately equal") |
list(string) |
form.validationErrors |
validations failing |
any |
[field].[<any other key>] |
Any other field key provided in form config is just passed down |
function(string, any) |
[field].set('prop', value) |
Any other field key can be changed using .set |
Field-level prop usage example
// ... { const email = thispropsemail; const className = return <input ='email' = = = = = /> }// ...