Components

Collection Form FormContext Props Basic usage Reducers Validation - Sync Validation - Async Input PersistStateOnUnmount Select TextArea

Hooks

Material UI - React Select

FormContext

A React component that provides a more in-depth context of the "Form".

Props

onInit: function

A function invoked when the Form is initialized.

const onInit = (formState, isFormValid) => { // some operation }

onChange: function

A function invoked when any Form Field changes its value.

const onChange = (formState, isFormValid) => { // some operation }

onReset: function

A function invoked when the form has been reset to its initial State.

const onReset = (formState, isFormValid) => { // some operation }

onSubmit: function

A function invoked when the submit button has been pressed.
The function may return either a Promise or a boolean value of true/false.

const onSubmit = (formState) => { // some operation };
const onSubmit = (formState) => new Promise((resolve, reject) => { // some async operation  });

Cases:
- If the function returns a Promise which is resolved, it will increment the value named submitted.
- If the function returns a boolean value true, or no return at all, it will increment the value named submitted.
- If the function returns a Promise which is rejected, the value named submitted will not be incremented.
- If the function returns a boolean value false, the value named submitted will not be incremented.

const { submitted, submitAttempts } = useForm();

It will be only invoked if your form passes all validations added at any level (Collections or Fields).
For each invocation, the value submitAttempts will be incremented.

initialState: object

It is a plain object that represents the initial state of the form.

reducers: array | function

(nextState, prevState) => nextState

An array whose values correspond to different reducer functions.
Reducer functions specify how the Form's state changes.

touched: boolean

Default value of false.
If true, sync validation messages will be shown but only when the event onBlur of any forms's field is triggered by a user action at any level of nesting.

Basic usage

import { useForm } from 'usetheform'
export const Form = ({ children }) => {
  const { onSubmitForm } = useForm();
  return (
    <form onSubmit={onSubmitForm}>
      {children}
    </form>
  );
};

root:{} 0 keys

() => {
  const Tags = () => {
    const [tags = [], setTags] = useSelector(state => state.tags)
    const resetTag = target =>
      setTags(prev => prev.filter(val => val !== target))
    return tags.map((tag, index) => (
      <button type="button" key={tag} onClick={() => resetTag(tag)}>
        {`${tag} X`}
      </button>
    ))
  }
  const onSubmit = state => alert(JSON.stringify(state))
  return (
    <FormContext onSubmit={onSubmit}>
      <Form>
        <Collection array name="tags">
          <Input
            type="checkbox"
            value="Blue"
            checked
            placeholder="Tag Blue"
          />
          <Input type="checkbox" value="Red" placeholder="Tag Red" />
          <Input type="checkbox" value="Pink" placeholder="Tag Pink" />
        </Collection>
        <button type="submit">Submit</button>
      </Form>
      <Tags />
    </FormContext>
  )
}

() => {
  const Tags = () => {
    const [tags = [], setTags] = useSelector(state => state.tags)
    const resetTag = target =>
      setTags(prev => prev.filter(val => val !== target))
    return tags.map((tag, index) => (
      <button type="button" key={tag} onClick={() => resetTag(tag)}>
        {`${tag} X`}
      </button>
    ))
  }
  const onSubmit = state => alert(JSON.stringify(state))
  return (
    <FormContext onSubmit={onSubmit}>
      <Form>
        <Collection array name="tags">
          <Input
            type="checkbox"
            value="Blue"
            checked
            placeholder="Tag Blue"
          />
          <Input type="checkbox" value="Red" placeholder="Tag Red" />
          <Input type="checkbox" value="Pink" placeholder="Tag Pink" />
        </Collection>
        <button type="submit">Submit</button>
      </Form>
      <Tags />
    </FormContext>
  )
}

Reducers

import { FormContext, Input } from 'usetheform'

root:{} 0 keys

() => {
  const maxNumber10 = (nextState, prevState) => {
    if (nextState.myNumber > 10) {
      nextState.myNumber = 10
    }
    return nextState
  }
  const minNumber1 = (nextState, prevState) => {
    if (nextState.myNumber <= 1) {
      nextState.myNumber = 1
    }
    return nextState
  }
  return (
    <FormContext reducers={[minNumber1, maxNumber10]}>
      <Form>
        <Input
          type="number"
          name="anyNumber"
          value="1"
          placeholder="Number"
        />
      </Form>
    </FormContext>
  )
}

() => {
  const maxNumber10 = (nextState, prevState) => {
    if (nextState.myNumber > 10) {
      nextState.myNumber = 10
    }
    return nextState
  }
  const minNumber1 = (nextState, prevState) => {
    if (nextState.myNumber <= 1) {
      nextState.myNumber = 1
    }
    return nextState
  }
  return (
    <FormContext reducers={[minNumber1, maxNumber10]}>
      <Form>
        <Input
          type="number"
          name="anyNumber"
          value="1"
          placeholder="Number"
        />
      </Form>
    </FormContext>
  )
}

Validation - Sync

Validation at FormContext level:

touched=false: error messages will be shown on FormContext initialization and when any Field is edited.
touched=true: error messages will be shown when any Field at any level of nesting is touched/visited.

import { FormContext, Input, Collection, useValidation } from 'usetheform'

root:{} 0 keys

() => {
  const graterThan10 = ({ values }) =>
    values && values['A'] + values['B'] > 10 ? undefined : 'A+B must be > 10'
  const [status, validationProps] = useValidation([graterThan10])
  return (
    <FormContext touched {...validationProps}>
      <Form>
        <Collection object name="values">
          <Input type="number" name="A" placeholder="Number A" value="1" />
          <Input type="number" name="B" placeholder="Number B" value="2" />
        </Collection>
        {status.error && <label>{status.error}</label>}
        <button type="submit">Press to see results</button>
      </Form>
    </FormContext>
  )
}

() => {
  const graterThan10 = ({ values }) =>
    values && values['A'] + values['B'] > 10 ? undefined : 'A+B must be > 10'
  const [status, validationProps] = useValidation([graterThan10])
  return (
    <FormContext touched {...validationProps}>
      <Form>
        <Collection object name="values">
          <Input type="number" name="A" placeholder="Number A" value="1" />
          <Input type="number" name="B" placeholder="Number B" value="2" />
        </Collection>
        {status.error && <label>{status.error}</label>}
        <button type="submit">Press to see results</button>
      </Form>
    </FormContext>
  )
}

Async Validation for FormContext is triggered on the Submit event. The form submission is prevented if the validation fails. This means that the onSubmit function passed as a prop to the FormContext component will not be invoked.

import { FormContext, Collection, Input, useAsyncValidation } from 'usetheform';

root:{} 0 keys

() => {
  const [asyncStatus, validationProps] = useAsyncValidation(asyncTestForm)
  const onSubmit = state => alert(JSON.stringify(state))
  return (
    <FormContext onSubmit={onSubmit} {...validationProps}>
      <Form>
        <Collection object name="values">
          <Input type="number" name="a" placeholder="Number A" value="1" />
          <Input type="number" name="b" placeholder="Number B" value="2" />
        </Collection>
        {asyncStatus.status === undefined && (
          <label>Async Check Not Started Yet</label>
        )}
        {asyncStatus.status === 'asyncStart' && <label>Checking...</label>}
        {asyncStatus.status === 'asyncError' && (
          <label>{asyncStatus.value}</label>
        )}
        {asyncStatus.status === 'asyncSuccess' && (
          <label>{asyncStatus.value}</label>
        )}
        <Submit />
      </Form>
    </FormContext>
  )
}

() => {
  const [asyncStatus, validationProps] = useAsyncValidation(asyncTestForm)
  const onSubmit = state => alert(JSON.stringify(state))
  return (
    <FormContext onSubmit={onSubmit} {...validationProps}>
      <Form>
        <Collection object name="values">
          <Input type="number" name="a" placeholder="Number A" value="1" />
          <Input type="number" name="b" placeholder="Number B" value="2" />
        </Collection>
        {asyncStatus.status === undefined && (
          <label>Async Check Not Started Yet</label>
        )}
        {asyncStatus.status === 'asyncStart' && <label>Checking...</label>}
        {asyncStatus.status === 'asyncError' && (
          <label>{asyncStatus.value}</label>
        )}
        {asyncStatus.status === 'asyncSuccess' && (
          <label>{asyncStatus.value}</label>
        )}
        <Submit />
      </Form>
    </FormContext>
  )
}

Detailed Explanation:

import { useForm } from 'usetheform'
const Submit = () => {
  const { isValid } = useForm();
  return (
    <button disabled={!isValid} type="submit">
      Submit
    </button>
  );
};
export const asyncTestForm = ({ values }) =>
  new Promise((resolve, reject) => {
    // it could be an API call or any async operation
    setTimeout(() => {
      if (!values || !values.a || !values.b) {
        reject("Emtpy values are not allowed ");
      }
      if (values.a + values.b >= 5) {
        reject("The sum must be less than '5'");
      } else {
        resolve("Success");
      }
    }, 1000);
  });