Skip to content

varHarrie/react-hero-form

Repository files navigation

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.

About

A full-featured form component.

Resources

License

Stars

Watchers

Forks

Packages

No packages published