useField

The

useField

hook is used to control input components such as TextInput or Checkbox. It combines state management and validation in a single utility.

Checkout the Forms Guide for an in depth guide on how to use it.

Do's & Don'ts

If used with boolean values, make sure to pass a default boolean value to make it work correctly.

Params

All params are passed as an object.

Name	Type	Default	Description
name*	string		The HTML `name` value
value	string, bool	''	The default value
showValidationOn	change \| blur		Whether the validation should be triggered on a different event. By default, it is triggered on submit.
validation	object		A key value mapping of error message - validation function pairs. A validation function can either be a function of the current value or a regular expression.
requiredErrorMessage	string	This field is required.	The error message that is shown if the input is required, but empty.
loading	bool	false	The initial loading state
touched	bool	false	The initial touched state
disabled	bool	false	The initial disabled state
required	bool	false	The initial required state
format	function		The formatting function that's applied on value when it changes

Returns

Object

: An object containing all relevant field values having the following shape:

const shape = {
  // includes all the props required to render a component
  props,
  // the passed input name
  value,
  // the loading state
  loading,
}

const shape = {
  // includes all the props required to render a component
  props,
  // the passed input name
  value,
  // the loading state
  loading,
}

Examples

Dark Mode

function Component() {
  const firstName = useField({
    name: 'firstname',
    showValidationOn: 'change',
    validation: {
      'Your first name must at least have two characters.': (value) =>
        value.trim().length >= 2,
    },
  })

  return <TextInput {...firstName.props} />
}function Component() {
  const firstName = useField({
    name: 'firstname',
    showValidationOn: 'change',
    validation: {
      'Your first name must at least have two characters.': (value) =>
        value.trim().length >= 2,
    },
  })

  return <TextInput {...firstName.props} />
}