Form

What is this?

A performant form state handling library. It has a first-class typescript support, and easy field validation.

Simple form

SyntaxError: Identifier 'TextInput' has already been declared

Validation

Normal

SyntaxError: Identifier 'TextInput' has already been declared

Using Yup

Yup is a schema builder for runtime value parsing and validation

SyntaxError: Identifier 'TextInput' has already been declared

Watchers

useWatch

firstName:

age:

Watch

firstName:

age:

Components

Checkbox

SyntaxError: Identifier 'CheckboxGroup' has already been declared

Radio

SyntaxError: Identifier 'RadioGroup' has already been declared

Switch

SyntaxError: Identifier 'Switch' has already been declared

NumberInput

SyntaxError: Identifier 'NumberInput' has already been declared

Select

SyntaxError: Identifier 'Select' has already been declared

TextArea

SyntaxError: Identifier 'TextArea' has already been declared

TextInput

SyntaxError: Identifier 'TextInput' has already been declared

Installation

The admin-ui-form package is not included in the admin-ui bundle, so you must add it.

# with yarn
yarn add @vtex/admin-ui-form

# with npm
npm install @vtex/admin-ui-form

Usage

import { Form, useFormState } from '@vtex/admin-ui-form'

function Example() {
  const form = useFormState()

  const handleSubmit = (data) => {
    // form data
  }

  return (
    <Form state={form} onSubmit={handleSubmit}>
      {/** ... components ... */}
      <Button type="submit">Submit</Button>
    </Form>
  )
}

Key concepts

To understand how this library works you need first to understand some concepts.

Name

This property specifies the name of the input, and it is used to subscribe to it. You can pass this prop to every component in this library.

Subscriptions

The ability to watch individual inputs and formState updates without re-rendering the entire form. There are two ways of subscribing to an input element: using the Watch component or the useWatch hook. They can be used as a replacement for the onChange callback.

Watch

SyntaxError: Identifier 'TextInput' has already been declared

useWatch

SyntaxError: Identifier 'TextInput' has already been declared

State hook

This hook is what makes it possible to subscribe to each form input and isolate the re-render at the hook level. It has its scope in terms of subscriptions, so it does not affect other useFormState.

defaultValues

Use the state prop defaultValues to load form components with initial values. The keys of this object must have the same name you set for the component.

SyntaxError: Identifier 'TextInput' has already been declared

Props

Form

Extends all props of <form> JSX element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-

TextInput

Extends all props of the TextInput Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

NumberInput

Extends all props of the NumberInput Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

TextArea

Extends all props of TextArea JSX element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

Select

Extends all props of the Select Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

Radio

Extends all props of the Radio Admin UI element.

RadioGroup

Extends all props of the RadioGroup Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

Checkbox

Extends all props of the Checkbox Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

CheckboxGroup

Extends all props of the CheckboxGroup Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-
name	string	Field name	✅	''
validation	ValidationOptions	Field validation options	🚫	-

Switch

Extends all props of the Switch Admin UI element.

Name	Type	Description	Required	Default
state	FormState	Return of useFormState	✅	-

useWatch

React Hook to subscribe to input changes. It returns the input value state.

Name	Type	Description	Required	Default
form	FormState	Return of useFormState	✅	-
name	string	Field name	✅	-

Watch

React Component to subscribe to input changes. It renders the input value state.

Name	Type	Description	Required	Default
form	FormState	Return of useFormState	✅	-
name	string	Field name	✅	-

Shared types

FormState

All values returned by the useFormState hook.

Name	Type	Description
register	(name: string, validation: ValidationOptions) => ({ onChange, onBlur, name, ref })	Allows you to register and subscribe an input element
formState	Object	This object contains information about the entire form state. It helps you to keep on track with the user's interaction with your form application.
watch	(names?: string, string[], (value, options) => void) => unknown	This method will watch specified inputs and return their values. It is useful to render input value and for determining what to render by condition.
resetField	(name: string, options?: Record<string, boolean, any>) => void	Reset an individual field state.
setError	(name: string, error: FieldError, { shouldFocus?: boolean }) => void	The function allows you to manually set one or more errors.
clearErrors	(name?: string, string[]) => void	This function can manually clear errors in the form.
setValue	(name: string, value: unknown) => void	This function allows you to dynamically set the value of a registered field and have the options to validate and update the form state. At the same time, it tries to avoid unnecessary rerender.
getValues	(payload?: string, string[]) => Object	An optimized helper for reading form values. The difference between watch and getValues is that getValues will not trigger re-renders or subscribe to input changes.

ValidationOptions

Validation rules are all based on the HTML standard and also allow for custom validation methods.

Name	Type	Description
required	boolean	Indicates whether the input must have a value before the form can be submitted or not
maxLength	number	The maximum length of the value to accept for this input
minLength	number	The minimum length of the value to accept for this input
max	number	The maximum value to accept for this input
min	number	The minimum value to accept for this input
pattern	RegExp	The regex pattern for the input
validate	Function, Object	You can pass a callback function as the argument to validate, or you can pass an object of callback functions to validate all of them. This function will be executed on its own without depending on other validation rules including the required attribute
valueAsNumber	boolean	Returns a Number normally. If something goes wrong NaN will be returned.
valueAsDate	boolean	Returns a Date object normally. If something goes wrong Invalid Date will be returned
disabled	boolean = false	Set disabled to true will lead input value to be undefined and input control to be disabled
onChange	(event) => void	onChange function event to be invoked in the change event
onBlur	(event) => void	onBlur function event to be invoked in the blur event
shouldUnregister	boolean	Input will be unregistered after unmount and defaultValues will be removed as well
deps	string, string[]	Validation will be triggered for the dependent inputs

• What is this?
• Simple form
• Validation
  • Normal
  • Using Yup
• Watchers
  • useWatch
  • Watch
• Components
  • Checkbox
  • Radio
  • Switch
  • NumberInput
  • Select
  • TextArea
  • TextInput