This library is still in development and is available only for internal usage at VTEX.

Form

Version: 0.133.0

Form

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

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>
  )
}

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

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.

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.

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.

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.

Extends all props of <form> JSX element.

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

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	🚫	-

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	🚫	-

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	🚫	-

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	🚫	-

Extends all props of the Radio Admin UI element.

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	🚫	-

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	🚫	-

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	🚫	-

Extends all props of the Switch Admin UI element.

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

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	✅	-

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	✅	-

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.

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

What is this?​

Simple form​

Validation​

Normal​

Using Yup​

Watchers​

useWatch​

Watch​

Components​

Checkbox​

Radio​

Switch​

NumberInput​

Select​

TextArea​

TextInput​

Installation​

Usage​

Key concepts​

Name​

Subscriptions​

Watch​

useWatch​

State hook​

defaultValues​

Props​

Form​

TextInput​

NumberInput​

TextArea​

Select​

Radio​

RadioGroup​

Checkbox​

CheckboxGroup​

Switch​

useWatch​

Watch​

Shared types​

FormState​

ValidationOptions​

What is this?

Simple form

Validation

Normal

Using Yup

Watchers

useWatch

Watch

Components

Checkbox

Radio

Switch

NumberInput

Select

TextArea

TextInput

Installation

Usage

Key concepts

Name

Subscriptions

Watch

useWatch

State hook

defaultValues

Props

Form

TextInput

NumberInput

TextArea

Select

Radio

RadioGroup

Checkbox

CheckboxGroup

Switch

useWatch

Watch

Shared types

FormState

ValidationOptions