Skip to main content

useField

useField(options: Object) allows custom input primitives to be built.

  const fieldInputProps = useField(options)

Arguments​

options: object

  • type: string

  • name: string

    • A field's name in Usetheform state.
    • If your Field 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 your Field is rendered within a <Collection array /> .

  • value: string | number | object (only for type="custom")

    • Specifies the initial value of an input element.

  • checked: boolean

    • Specifies whether an input element should be pre-selected or not (for type="checkbox" or type="radio").
    • Default value of false.

  • multiple: boolean

    • Valid only when type="select".
    • When present, it specifies that multiple options can be selected at once.
    • Default value of false.

  • touched: boolean

    • A field that has been touched/visited.
    • Default value of false.
    • If true, validation messages (sync and async) will be shown only when the event onBlur of the field is triggered by a user action.

  • reducers: array | function

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

Returns​

(FieldInputProps): object

  • An object that holds all the attributes of a field.

Basic usage​

CustomInput.ts
const CustomInput = props => {
  const fieldInputProps = useField({
    type: "text",
    name: "simple",
    value: "foo"
  });
  return <input {...fieldInputProps} />;
}
CustomField.ts
const CustomField = ({ name, initialValue = { a: "2" } }) => {
  const { value, setValue } = useField({ type: "custom", name, value: initialValue });
  const onChange = () => setValue(prev => ({ ...prev, a: "1" }));
  return (
    <div>
      <pre>
        <code>{JSON.stringify(value)}</code>
      </pre>
      <button type="button" onClick={onChange}>
        Change Value
      </button>
    </div>
  );
};

Reducers​

CustomInput.ts
const maxNumber10 = (nextValue, prevValue) => nextValue > 10 ? prevValue : nextValue;
const minNumber1 = (nextValue, prevValue) => nextValue <= 1 ? prevValue : nextValue;

const CustomInput = props => {
  const fieldInputProps = useField({
      type: "number",
      name: "numberWithReducer",
      reducers: [minNumber1, maxNumber10],
      value: "1"
    });
  return <input {...fieldInputProps} />;
}

Validation​

CustomInput.ts
const email = value =>
    !(value && !/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$/i.test(value))
      ? undefined
      : "Mail not Valid";
const required = value => (value && value.trim() !== "" ? undefined : "Required");

const CustomInput = props => {
  const [status, validation] = useValidation([required, email]);
  const fieldInputProps = useField({
      type: "text",
      touched: true,
      name: "email",
      ...validation
  });
  return (
    <div>
      <input {...fieldInputProps} />
      {status.error && <label>{status.error}</label>}
    </div>
  )
}