Introduction

This React Form component helps you:

• Maintain Form state
• Debounced field validation
• Validate field asynchronously
• Handle form submission
• prevent multiple form submission
• Reduce field re-render by detecting if field value changes

Installation

Install lodash (">=4.17.15") and rxjs (">=6.5.x) if you don't have it.

npm install --save lodash rxjs

Install react-form

npm install --save @danny-ui/react-form

Usage

import { Form, useField } from '@danny-ui/react-form';

function TextField({
  name = '',
  label = '',
  required = false,
  defaultValue = '',
  validate,
  type = 'text',
}) {
  const { value, onChange, meta } = useField({
    name,
    displayName: label,
    validate,
    required,
    defaultValue,
  });

  return (
    <div>
      <label>{label}</label>
      <input
        onChange={(ev) => onChange(ev.target.value)}
        value={value}
        type={type}
      />
    </div>
  );
}

<Form
  onSubmit={async (value) => {
    window.alert(JSON.stringify(value));
  }}
>
  <TextField
    required
    validate={async (value) => {
      await new Promise((res) => setTimeout(res, 100));
      const isEmailValid = /^[^@]+@[^@]+\.[^@]+$/.test(value);
      return !isEmailValid && new Error('Invalid Email Address');
    }}
    label="Email Address"
    name="email"
  />
  <TextField required name="password" label="Password" type="password" />
  <button type="submit">Submit</button>
</Form>;

Examples

Please check examples here.

API

Form Properties

| Name | Type | Description | | -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children* | node | The content of the form, normally Field component with useField hook. | | onSubmit* | func | Callback fired when the form is submitted. Signature: function(value: object, meta: object) => Promise Return value of onSubmit function will be passed to success callback | | success | func | Callback fired when onSubmit function is resolved. Signature: function(submitReturn: any, value: object) => Promise | | failed | func | Callback fired when onSubmit function is rejected. Signature: function(errors: [Error], value: object) => void | | beforeSubmit | func | Callback fired before onSubmit function is called. Signature: function(values: object, meta: object) => Promise | | extendFormMeta | func | Callback fired after an action updated form state. The return object will be merged into form meta Signature: function(state: object) => object | | className | string | css apply to form |

useField Properties

| Name | Type | Description | | --------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | | name* | string | key to lookup form value | | defaultValue* | any | default field value | | required | bool | if true, field onChange action and form onSubmit will check if this field value is empty | | displayName | string | use with required props, and display the error message as `${displayName} is required` | | destroyValueOnUnmount | bool | When field unmount, determine whether to destroy the field value or not | | validate | func | Callback fired when field value changed. Signature: function(value: object) => Promise |

FormValues Properties

| Name | Type | Description | | ---------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children* | func | It exposes the formValue and it is normally used for linked fields. Signature: function(value: object) => node | | filter | func | It is used to improve performance. You can use it to control if the children function should be called. Similar to react shouldComponentUpdate life circle Signature: function(value: object) => bool |

FieldOnChange Properties

| Name | Type | Description | | ---------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children* | func | It can detect field onChange action and you can use it to update associated fields. Signature: function(props: object) => void props: an object type of {action, formValues, updateFormValues: (changes: {path: string, value: any}[]) => void} |

FormMeta Properties

| Name | Type | Description | | ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children* | func | It exposes the form meta and provides the current form state. It is normally used for buttons. Signature: function(formMeta: object) => node |

License

MIT License.