Skip to content

Latest commit

 

History

History
152 lines (117 loc) · 4.25 KB

README.md

File metadata and controls

152 lines (117 loc) · 4.25 KB

@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. Each function should return a boolean or string value:

  • Returning true means check successfully.
  • Returning false or string means check failed, and the string result is the error message.

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.

const rules = {
  name: (!!val && !!val.trim()) || 'Name is required'
}

const store = new FormStore({}, rules)
// ...
const [error, values] = store.validate()

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, false) Sets field value by name without validating.
  • store.reset() Resets form with default values.
  • store.validate() Validates entire form and returns error message and values.
  • store.validate(name) Validates field value by name and returns error message and 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.