veasy

An elegant react form solution which focus on form validation and more.

Usage no npm install needed!

<script type="module">
  import veasy from 'https://cdn.skypack.dev/veasy';
</script>

README

Veasy.js

Veasy.js

npm version npm Build Status Coverage Status

A comprehensive react form solution which aims to eliminate all tedious logic.

Documentation

Features

  • Field validation (We handle the validation logic!)
  • Form status (check whether all fields ready or not)
  • Generate initial state with default value
  • Get fields value for submitting
  • Auto update fields props according to validation result
  • Auto binding fields props
  • Support chaining validation, field A reliesOn field B with different rules
  • onBlur: trigger validation automatically
  • onChange: trigger validation automatically
  • onReset: reset form to default state
  • Need more features? Raise an issue :)

Why use

  • Declarative way to define your validation rule
  • Comprehensive validation rule set and easy to extend
  • Progressive validation mechanism.
  • Highly customizable: error message, default state, whatever you want.
  • Clean JSX hierarchy, use your own field item component.
  • Promise based architecture.
  • Handle all the tedious logic without learning too much.

Install

npm install --save veasy

A quick 2 steps how to

Suppose you have a form field component:

<FieldItem name="title" />

Step 1: You can write a schema using json

import VeasyForm, {createInitialState} from 'veasy';

// `title` here should match the name of the field
const formSchema = {
  title: {
    minLength: 10,
    maxLength: 20,
    exclude: 'bad words'
  }
};

// Then setup the initial state in the component's constructor
// Find out add your own state in the doc
this.state = createInitialState(formSchema);

Step 2: Auto bind the props

Then wrap using our <VeasyForm> component:

<VeasyForm
  schema={formSchema}
  allState={this.state}
  update={(fieldState) => {this.setState(fieldState);}}
>
  <FieldItem name="title" />
</VeasyForm>

Congrats! Now you automatically get the following features:

  1. Your FieldItem will get the following props at runtime:
    • status: For changing the look, ('normal', 'ok' and 'error')
    • errorText: For showing the error message.
    • value: Like how you bind the value for every controlled component :)
    • onChange: A change handler for handling the validation when user changing the value.
  2. Anytime the user changes something, the above 3 props will auto updated by Veasy
  3. OnChange and onBlur will auto trigger the validation as well.
  4. isFormOK will be true when all fields's status equals to ok.
  5. onReset has been handled for resetting the state to initial state, you just need to add a plain form reset button ( < button type='reset' > ).

There is even a getFieldsValue() method for you to get all the fields value, even you don't include all the fields in the schema, we cover that case for you :)

Check the working code example at here.

Tip: There is an extra isFormOK prop at the root level of state to indicate the status of the form according to all the fields defined in the schema.

Now you get it! Let's take several minutes to go through our documentation.

Chaining rules and Progressive validation mechanism

  • Rules in schema are processed one-by-one.
  • Unless the value passes the first rule, Veasy won't bother checking the next.

Many forms in the wild display all errors at once, which can be many! That's scary!

Instead, we guide the user through the form by validating each rule one-by-one. As a very simple example, consider this field which expects an int, min and max.

Your schema is like this:

{
  age: {
    isInt: true,
    min: [16, 'should be older than 16'],
    max: 99
  }
}

If the user enters one, veasy will stop at first rule and let the user know that it should be a number. If they then enter 1, veasy will inform them that they should be older than 16, and so on until all rules are valid.

This example is simple, you can chain all the rules to build your own. And thanks to React, it all happens immediately. All you need to do is to declare a schema.

Gitter channel

https://gitter.im/veasyjs/Lobby