usetheform
Edit page
Introduction
Components
Hooks
useAsyncValidationuseCollectionArgumentsReturnsBasic usageReducersValidationuseFielduseFormuseMultipleFormuseSelectoruseValidation
Material UI - React Select

useCollection

useCollection(options: Object) allows a custom Collection to be built.

A Collection can be of type: object or array.

const { value, state, updateCollection } = useCollection(options)

Arguments

options: object

  • object: boolean

    • It creates a collection of type object if "true".

  • array: boolean

    • It creates a collection of type array if "true".

  • name: string

    • A field's name in Usetheform state.
    • If it is rendered within a <Collection array />, name is not allowed as a prop.

  • index: string

    • A field's index in an array Collection.
    • index is only allowed if it is rendered within a <Collection array /> .

  • value: array | object

    • Specifies the initial value of a Collection which can be either an array or an object.

  • reducers: array | function

    • An array whose values correspond to different reducer functions.
    • Reducer functions specify how the Collection's value changes.
(nextValue, prevValue, formState) => nextValue

Returns

(helpers): object

An object that holds:

  • value: the current value of the Collection. It can be an array or an object.
  • updateCollection: a function which can change one prop of the Collection.
  • state: the current State of the entire Form.

Basic usage

import { useCollection } from "usetheform";
const CustomCollection = props => {
  const { value, state, updateCollection } = useCollection({
    name: "test",
    type: "object",
    value: { name: "foo" } // an initialValue if needeed
  });
  // it changes the prop "name" of the Collection named "test"
  const onUpdateCollection = () => updateCollection("name", "mickey");
  
  return (
    <div>
      <span>{value.name}<span>
      <button type="button" onClick={onUpdateCollection}>
        Update Collection
      </button>
    </div>
  );
}

Reducers

import { useCollection } from "usetheform";
const maxNumber10 = (nextValue, prevValue) => nextValue > 10 ? prevValue : nextValue;
const minNumber1 = (nextValue, prevValue) => nextValue <= 1 ? prevValue : nextValue;
const CustomCollection = props => {
  const { value, state, updateCollection } = useCollection({
    name: "test",
    type: "object",
    value: { number: 10 } // an initialValue if needeed
    reducers: [minNumber1, maxNumber10],
  });
  
  const onIncrement = () => updateCollection("number", value.number + 1 );
  const onDecrement = () => updateCollection("number", value.number - 1 );
  return (
    <div>
      <span>{value.number}<span>
      <button type="button" onClick={onIncrement}>
        Increment
      </button>
      <button type="button" onClick={onDecrement}>
        Decrement
      </button>
    </div>
  );
}

Validation

Validation for Collection starts only on form submission.

import { useValidation, useCollection } from "usetheform";
const lessThan10 = value => {
  return value && value.number && value.number <= 10
    ? undefined
    : "Number not valid";
};
const graterThan0 = value =>
  value && value.number && value.number >= 0 ? undefined : "Number not valid";
const CustomCollection = props => {
  const [status, validation] = useValidation([lessThan10, graterThan0]);
  const { value, updateCollection } = useCollection({
    name: "test",
    type: "object",
    value: { number: 9 }, // an initialValue if needeed
    ...validation
  });
  const onIncrement = () => updateCollection("number", value.number + 1);
  const onDecrement = () => updateCollection("number", value.number - 1);
  return (
    <div>
      <span>{value.number}</span>
      {status.error && <label>{status.error}</label>}
      <button type="button" onClick={onIncrement}>
        Increment
      </button>
      <button type="button" onClick={onDecrement}>
        Decrement
      </button>
    </div>
  );
}