react-form-mobx v1.0.0

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

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

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

ArrayOf Component

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

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

Props

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

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

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

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