react-hero-form

A full-featured form component.

Installation

npm install react-hero-form --save
# or
yarn add react-hero-form

Basic Usage

Simply create a FormStore and pass into Form component. value and onChange of form controls (such as input) are unnecessary.

import { Form, FormStore } from "react-hero-form";

class App extends React.Component {
  constructor(props) {
    super(props);
    this.store = new FormStore();
  }

  onSubmit = e => {
    e.preventDefault();

    const values = this.store.get();
    console.log(values);
  };

  render() {
    return (
      <Form store={this.store}>
        <Form.Field label="Name" name="name">
          <input type="text" />
        </Form.Field>
        <Form.Field label="">
          <button onClick={this.onSubmit}>Submit</button>
        </Form.Field>
      </Form>
    );
  }
}

Simple Field

Form.Item is a simplified version of Form.Field, without any extra nodes.

<Form store={this.store}>
  <Form.Item name="username">
    <input type="text" />
  </Form.Item>
  <Form.Item name="password">
    <input type="password" />
  </Form.Item>
</Form>

will renders into:

<form>
  <input type="text" />
  <input type="password" />
</form>

Default Values

To set default values, you can pass an object as the first parameter. Use reset() to restore defaults at any time.

const store = new FormStore({ name: "Harry" });
// ...
store.reset();

Form Validation

The second parameter is used to pass the form rules.

Using store.validate() to check entire form, and returns a tuple with error message and form values. Or directly gets form values by store.get() without validation.

function assert(condition, message) {
  if (!condition) throw new Error(message)
}

const rules = {
  name: (val) => assert(!!val && !!val.trim(), "Name is required")
};

const store = new FormStore({}, rules);
// ...
try {
  const values = await store.validate();
  console.log('values:', values);
} catch (error) {
  console.log('error:', error);
}

APIs

Form Props

• className Form element class name, optional.
• store Form store, required.
• inline Inline layout for fields, default to false.
• compact Hides error message, default to false.
• required Displays star mark, does not include validation, default to false.
• labelWidth Customized label width, optional.
• gutter Customized distance between label and control, optional.
• errorClassName Adds customized class name when field has error message, optional.
• onSubmit Submit callback, optional.

Form Field Props

• className Field element class name, optional.
• label Field label, optional.
• name Field name, optional.
• valueProp Value prop name of child component, default to 'value'.
• valueGetter The way to parse value from change event, optional.
• suffix Suffix nodes, optional.

Form Item Props

• className Field element class name, optional.
• name Field name, optional.
• valueProp Value prop name of child component, default to 'value'.
• valueGetter The way to parse value from change event, optional.

FormStore Methods

• new FormStore(defaultValues?, rules?) Creates form store.
• store.get() Returns entire form values.
• store.get(name) Returns field value by name.
• store.set() Sets entire form values.
• store.set(name, value) Sets field value by name.
• store.set(name, value, true) Sets field value by name and validate.
• store.reset() Resets form with default values.
• store.validate() Validates entire form and returns values.
• store.validate(name) Validates field value by name and returns value.
• store.error() Returns the all error messages.
• store.error(index) Returns the nth error message.
• store.error(name) Returns error message by name.
• store.error(name, message) Sets error message by name.
• store.subscribe(listener) Adds listener and returns unsubscribe callback.

Hooks

• useFormStore(defaultValues?, rules?) Creates form store with hooks.
• useFormChange(store, onChange) Add form listener with hooks.
• useFieldChange(store, onChange) Add field listener with hooks.