Wit Form

Field

<Field> is a component version of useField. It connects one input to the form without a separate hook call. Use it for simple inputs, or when you'd rather not write a component per input type.

import { Field } from 'wit-form';

It works in two ways.

With a child element

<Field> passes the field's props to its child element:

<Field name="email" required>
  <MyInput label="Email" />
</Field>

MyInput receives:

PropTypeDescription
valueanyThe current value, or '' when there is none.
onChange(event) => voidCall it with the input's change event. Reads event.target.value.
onBlur() => voidMarks the field as touched.
errorstring | null | undefinedThe error, once the field is touched.
touchedboolean | undefinedWhether the field is touched.
extraInfoanyThe field's extra info.

A plain <input> works directly, since it already calls onChange with an event:

<Field name="firstName">
  <input />
</Field>

With a render function

Pass a function as the child to control rendering yourself. Here onChange takes the value, not an event, which suits checkboxes, radio groups and custom widgets:

<Field name="agree">
  {({ value, onChange, error }) => (
    <label>
      <input
        type="checkbox"
        checked={!!value}
        onChange={() => onChange(!value)}
      />
      I agree {error}
    </label>
  )}
</Field>

The render function receives the same props as the child element, plus:

PropTypeDescription
isValidatingbooleanAn async validator is running.
isDirtybooleanThe value differs from the initial value.
ref(element: any) => voidAttach it to the input so a failed submit can focus it.

The other difference is that onChange(value, extraInfo?) works like setFieldValue from useField.

Props

name

Type: string · Required

The field's name. Same as useField's name.

children

Type: a React element, or (props) => ReactNode · Required

The input to connect: an element that receives the props above, or a render function.

required

Type: boolean · Default: false

Adds a "Required" error when the value is empty. Only used when there is no validate prop. Empty means any falsy value: '', undefined, null, 0 and false. For number or checkbox fields where 0 or false is a valid answer, write your own validate.

validate

Type: (value, other?) => string | null | undefined · Default: none

A validator, like useField's validate. When given, required is ignored.

validateCallback, schema, debounceValidation, skipUnregister

The same as the useField options of the same names.

depFields

Type: same as useField · Default: none

Fields whose values are passed to validate. See useField's depFields.

defaultValue

Type: any · Default: none

Used when there is no initial value. See useField's defaultValue.

ancestors

Type: { name: string; rowId: number }[] · Default: none

For fields inside field array rows. See useField's ancestors.

handleChange

Type: (value: any) => void · Default: none

Called with the new value after each change, in child element mode only. Use it to react to changes, like clearing another field.

When to use useField instead

<Field> covers the common cases. Use useField directly when you need:

  • typed values (useField<number>), or checked names (createFormHooks also has a typed Field);
  • a reusable input component that's used across many forms.

See both styles in the Field Component example.

On this page

With a child elementWith a render functionPropsnamechildrenrequiredvalidatevalidateCallback, schema, debounceValidation, skipUnregisterdepFieldsdefaultValueancestorshandleChangeWhen to use useField instead