useField

The useField hook is an alternative to the Field component. It can used to create custom Field components or encapsulate thorny logic.

function MyField({ name }) {
  const [props, meta] = useField(name);
}

useField will return a props object you can pass to an input component. Note that useField makes a best guess at constructing props for the input likely to receive them. It takes hints from type as well as as options to build props specific to the required input.

For instance, consider a checkbox field:

// formData = { isCool: true }
function IsCoolField() {
  const [props, meta] = useField({
    name: 'isCool',
    type: 'checkbox',
  });
  return <input {...props} />;
}

To accommodate the checkbox input, props here contains checked: true and value: undefined, since the true value from the from needs to be passed to the checked attribute of the input. You can often even leave out the type and React Formal will try and infer the type from the schema:

const schema = object({
  isCool: yup.boolean(),
});
// ...
function IsCoolField() {
  const [props, meta] = useField('isCool');
  // still has checked: true
  return <input {...props} />;
}

This also works for more complex examples like <select>s associated with arrays:

const schema = object({
  colors: yup.array(),
});
// ...
function ColorsField({ children }) {
  const [props, meta] = useField('colors');
  // <select multiple>
  return <select {...props}>{children}</select>;
}

As with before you can override the inferred behavior by explicitly passing type and/or as to useField. For non-native input as values React Formal will not infer any specfic props, instead passing just value, onChange, and onBlur. Details about the inferred types and inputs are always available on the field meta

#API

• #

  useField(name: string) => [UseFieldProps, FieldMeta]

  Create a new form field for the provided name, takes the same options as Field props.

  function MyNameField(props) {
    const [fieldProps, meta] = useField('firstName')
    return (
       <input
         {...fieldProps}
         className={meta.invalid ? 'field-error' : ''}
       />
    )
  }

  Parameters

  • namestring

    The Field name, which should be path corresponding to a specific form value path.

  Return Value

  [UseFieldProps, FieldMeta]

• #

  useField(options: UseFieldOptions) => [UseFieldProps, FieldMeta]

  Create a new form field for the provided name, takes the same options as Field props.

  function MyNameField(props) {
    const [fieldProps, meta] = useField({ name: 'firstName' })
    return (
       <input
         {...fieldProps}
         className={meta.invalid ? 'field-error' : ''}
       />
    )
  }

  Parameters

  • optionsUseFieldOptions
    • namestring

      The Field name, which should be path corresponding to a specific form value path.

    • value?any

      For checkbox/boolean fields override the HTML default value for checks from 'on'

    • mapToValue?MapToValue

      A mapper from the form value to fieldProps.value`

    • mapFromValue?string | MapFromValue

      A mapper from the form value to fieldProps.value`

    • validates?string | string[] | null

      Triggers validation for additional field paths

  Return Value

  [UseFieldProps, FieldMeta]