react-form-mobx

Declarative Form components for React, built on top of MobX

Table of Contents

• Table of Contents
• Philosophy
  • Features Included
  • Features NOT Included
• Live Demo
• Getting Started
  • Installing
  • Usage
• Advanced Guides
  • Dynamic Array Items
  • Creating Custom Input Component
• References
  • Form Component
  • Input Components
  • ObjectOf Component
  • ArrayOf Component
  • Submit, Reset, Clear Component
  • Demon Component
  • DemonButton Component
• License

Philosophy

Declarative, just like React and HTML

Features Included

• Support nested objects and arrays
• Easy to create custom Input (or Select, Checkbox, Radio, etc) components
• Easy to push, update or remove array items
• Built-in validations (eg required, pattern, enum, etc)
• Built-in formats (eg integer, number, boolean, etc)
• Support data transformers / filters

Features NOT Included

• No styles, just the original appearance, but you could add style easily
• No HTTP requests, but you could choose any HTTP request library you like

Live Demo

Live demo on codesandbox

Getting Started

Installing

yarn add react-form-mobx

You may also need to install react, mobx and mobx-react

yarn add react mobx mobx-react react-form-mobx

Usage

import React, { Component } from 'react';
import { Form, Input, ObjectOf } from 'react-form-mobx';

export default class MyFriend extends Component {
  myData = {
    name: 'Luke Skywalker',
    height: 172,
    colors: {
      hair: 'blond',
      skin: 'fair',
    },
  },

  handleSubmit = (data) => {
    console.log('data', data);
  };

  render() {
    return (
      <Form value={this.myData} onSubmit={this.handleSubmit}>
        <Input name="name" />
        <Input name="height" format="number" />
        <ObjectOf name="colors">
          <Input name="hair" />
          <Input name="skin" />
        </ObjectOf>
      </Form>
    );
  }
}

Advanced Guides

Dynamic Array Items

import React, { Component } from 'react';
import { Form, Input, ArrayOf } from 'react-form-mobx';

export default class MyFriend extends Component {
  myData = {
    name: 'Luke Skywalker',
    starships: ['X-wing', 'Imperial shuttle'],
  },

  handleSubmit = (data) => {
    console.log('data', data);
  };

  render() {
    return (
      <Form value={this.myData} onSubmit={this.handleSubmit}>
        <Input name="name" />
        <ArrayOf name="starships">
          {(starships, { push, removeBy }) =>
            <div>
              {starships.map((starship) =>
                <span key={starship}>
                  <Input name={starship} />
                  <button type="button" onClick={removeBy(starship)}>Remove</button>
                </span>
              )}
              <button type="button" onClick={push}>Add Starship</button>
            </div>
          }
        </ArrayOf>
      </Form>
    );
  }
}

Creating Custom Input Component

MyInput.js

import React, { Component } from "react";
import { Demon } from "react-form-mobx";

export default class MyInput extends Component {
  render() {
    return (
      <Demon forwardedProps={this.props}>
        {(props, { isInvalid, errorMessage }) => (
          <label>
            <input
              style={{ borderColor: isInvalid ? "red" : "green" }}
              {...props}
            />
            {isInvalid && <span style={{ color: "red" }}>{errorMessage}</span>}
          </label>
        )}
      </Demon>
    );
  }
}

MyApp.js

import React, { Component } from "react";
import { Form } from "react-form-mobx";
import MyInput from "./MyInput";

export default class MyApp extends Component {
  render() {
    return (
      <Form value={this.myData}>
        <MyInput name="name" />
        {/* ... */}
      </Form>
    );
  }
}

References

Form Component

import { Form } from 'react-form-mobx';

Form component, just like HTML form component.

Props

| Property | Description | Type | Default | | ------------- | ------------------------------------------------------------------- | -------- | ------- | | value | Form data | Object | {} | | onSubmit | Defines a function will be called when form submit | Function | | | onValid | Defines a function will be called when form is valid | Function | | | onInvalid | Defines a function will be called when form is invalid | Function | | | onValidChange | Defines a function will be called when form valid status changed | Function | | | onChange | Defines a function will be called when form data changed | Function | | | inputFilter | Defines a filter function will be called when providing a new value | Function | | | outputFilter | Defines a filter function will be called when getting output value | Function | |

Input Components

import { Input, Checkbox, Radio, Select, TextArea } from 'react-form-mobx';

These Input Components mean Input, Checkbox, Radio, Select, TextArea or other custom input components created by Demon.

Props

| Property | Description | Type | Default | | ---------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------- | | name | Field name | String Required | | | defaultValue | Default value when value is empty | Any | | | defaultChecked | Default checked, only work in checkable components (eg: Checkbox, Radio) | Boolean | | | format | Data format | "integer", "number", "string", "boolean", "date", "time", "dateTime" | | | required | Indicates whether field is required | Boolean | false | | enum | Validate a value from a list of possible values | Array of String | [] | | pattern | Validate from a regular expression | RegExp | | | maxLength | Validate a max length of the field | Number | | | minLength | Validate a min length of the field | Number | | | maximum | Validate if the field is less than or exactly equal to "maximum" | Number | | | exclusiveMaximum | Validate if the field is less than (not equal to) "exclusiveMaximum" | Number | | | minimum | Validate if the field is greater than or exactly equal to "minimum" | Number | | | exclusiveMinimum | Validate if the field is greater than or exactly equal to "exclusiveMinimum" | Number | | | validation | Defines a validator function, should throw error if invalid | Function | | | inputFilter | Defines a filter function will be called when providing a new value to form | Function | | | outputFilter | Defines a filter function will be called when getting output value from form | Function | | | withEmpty | Indicates whether submit empty value or not | "auto", true, false | "auto" |

The rest of the props are exactly the same as the original DOM attributes.

Notes

• withEmpty: If value is empty (saying "", undefined, null, {} or []):
  • "auto" (Default): Will submit empty value only if pristine value is NOT empty
  • true: Will submit empty value
  • false: Will not submit empty value

ObjectOf Component

import { ObjectOf } from 'react-form-mobx';

ObjectOf component provides nested fields.

Props

| Property | Description | Type | Default | | ------------ | ---------------------------------------------------------------------------- | ----------------- | ------- | | name | Field name | String Required | | | children | Nested input nodes | Node Required | | | onChange | Defines a function will be called when data changed | Function | | | inputFilter | Defines a filter function will be called when providing a new value to form | Function | | | outputFilter | Defines a filter function will be called when getting output value from form | Function | |

ArrayOf Component

import { ArrayOf } from 'react-form-mobx';

ArrayOf component provides array fields, and could be push, update or remove easily.

Props

| Property | Description | Type | Default | | ------------ | ---------------------------------------------------------------------------- | --------------------------- | ------- | | name | Field name | String Required | | | children | Nested input nodes or function child that should return a node | Node or Function Required | | | onChange | Defines a function will be called when data changed | Function | | | inputFilter | Defines a filter function will be called when providing a new value to form | Function | | | outputFilter | Defines a filter function will be called when getting output value from form | Function | |

Function Child

If children prop is a callback renderer function, it will provide two arguments:

• names <Array>: An array of unique names that could be used as the key and name props of chidren components
• helper <Object>: A helper object to manipulate the array:
  • push() <Function>: To push a new item
  • remove(name) <Function>: To remove a item by name
  • removeBy(name) <Function>: To create and return a remove(name) currying function

Please checkout Dynamic Array Items for usage example.

Submit, Reset, Clear Component

import { Submit, Reset, Clear } from 'react-form-mobx';

• Submit: Just like HTML button component. Will emit onSubmit() in Form when click.
• Reset: Just like HTML button component. Will reset all input values to pristine values in Form when click
• Clear: Just like HTML button component. Will clear all input values in Form when click.

Props

| Property | Description | Type | Default | | -------- | ----------- | ---- | ------- | | children | children | Node | |

The rest of the props are exactly the same as the original DOM attributes.

Demon Component

import { Demon } from 'react-form-mobx';

Demon component is the core of creating custom input components.

Props

| Property | Description | Type | Default | | ------------------------- | ------------------------------------------------------------ | ------------------- | ---------------------------------- | | name | Field name | String Required | | | children | Function child that should return a node | Function Required | | | forwardedProps | Forward props, Demon will decide to handle or forward them | Object | {} | | checkable | Indicates whether the component is checkable | Boolean | false | | getValueFromChangeEvent | Defines a function to get value in onChange arguments | Function | (ev) => ev.currentTarget.value | | getCheckedFromChangeEvent | Defines a function to get checked in onChange arguments | Function | (ev) => ev.currentTarget.checked | | getKeyFromKeyPressEvent | Defines a function to get key in onPress arguments | Function | (ev) => ev.key | | propOnChange | Defines the prop name of change event | String | "onChange" | | propOnKeyPress | Defines the prop name of key press event | String | "onKeyPress" | | propOnBlur | Defines the prop name of blur event | String | "onBlur" |

Function Child

children prop provides two arguments:

• proxyProps <Object>: Forwarded props object including value or checked, but excluding name, format, enum and other props only work in Demon component. Can be directly pass to child component (like <input {...proxyProps} />)

• validState <Object>: Valid state helper object, including:

  • errorMessage <String>: Error message. Would be empty if the status is valid
  • isValid <Boolean>: Would be true if the status is valid
  • isInvalid <Boolean>: Would be true if the status is invalid
  • isTouched <Boolean>: Is touched or not. Useful if you don't want to show errorMessage when field is not touched

Proxied Props

By default, onChange, onKeyPress, onBlur props will be proxied.

• onChange: Demon need to get the changed value or checked from the change event object to update value. You can change the getting function by setting getValueFromChangeEvent or getCheckedFromChangeEvent prop to Demon component.
• onKeyPress: Demon need to get the key from the keyPress event object to decide to submit. You can change the getting function by settting propOnKeyPress prop to Demon component
• onBlur: Demon need to listen to the blur event to set isTouched to true

Please checkout Creating Custom Input Component for usage example.

DemonButton Component

import { DemonButton } from 'react-form-mobx';

DemonButton component is the core of creating custom button (Submit, Reset or Clear) components.

Props

| Property | Description | Type | Default | | ----------------------- | ------------------------------------------------------------------ | -------------------------- | ---------------- | | children | Function child that should return a node | Function Required | | | type | Button type | "submit", "reset", "clear" | "submit" | | forwardedProps | Forward props, DemonButton will decide to handle or forward them | Object | {} | | getKeyFromKeyPressEvent | Defines a function to get key in onPress arguments | Function | (ev) => ev.key | | propOnKeyPress | Defines the prop name of key press event | String | "onKeyPress" |

Function Child

children prop provides one argument:

• proxyProps <Object>: Forwarded props object. Can be directly pass to child component (like <button {...proxyProps} type="button" />)

License

MIT