Form

Overview

Form component renders a value to be updated and validated by child Fields. Forms can be thought of as <input/>s for complex values, or models. A Form aggregates a bunch of smaller inputs, each in charge of updating a small part of the overall model. The Form will integrate and validate each change and fire a single unified onChange with the new value.

Validation errors can be displayed anywhere inside a Form with Message Components.

const defaultStr = yup.string().default("");

const customerSchema = yup.object({
  name: yup.object({
    first: defaultStr.required("please enter a first name"),
    last: defaultStr.required("please enter a surname")
  }),

  dateOfBirth: yup.date().max(new Date(), "Are you a time traveler?!"),

  colorId: yup
    .number()
    .nullable()
    .required("Please select a dank color")
});

<Form schema={customerSchema} defaultValue={customerSchema.default()}>
  <fieldset>
    <legend className="sr-only">name</legend>
    <label>
      Name
      <Form.Field name="name.first" placeholder="First name" />
    </label>
    <label>
      Surname
      <Form.Field name="name.last" placeholder="Surname" />
    </label>
    <Form.Message for={["name.first", "name.last"]} className="error" />
  </fieldset>

  <label>
    Date of Birth
    <Form.Field name="dateOfBirth" />
  </label>
  <Form.Message for="dateOfBirth" className="error" />

  <label>
    Favorite Color
    <Form.Field name="colorId" as="select">
      <option value={null}>Select a color...</option>
      <option value={0}>Red</option>
      <option value={1}>Yellow</option>
      <option value={2}>Blue</option>
      <option value={3}>other</option>
    </Form.Field>
  </label>
  <Form.Message for="colorId" className="error" />

  <Form.Submit type="submit">Submit</Form.Submit>
</Form>;

const defaultStr = yup.string().default("");
const customerSchema = yup.object({
  name: yup.object({
    first: defaultStr.required("please enter a first name"),
    last: defaultStr.required("please enter a surname")
  }),
  dateOfBirth: yup.date().max(new Date(), "Are you a time traveler?!"),
  colorId: yup
    .number()
    .nullable()
    .required("Please select a dank color")
});
<Form schema={customerSchema} defaultValue={customerSchema.default()}>
  <fieldset>
    <legend className="sr-only">name</legend>
    <label>
      Name
      <Form.Field name="name.first" placeholder="First name" />
    </label>
    <label>
      Surname
      <Form.Field name="name.last" placeholder="Surname" />
    </label>
    <Form.Message for={["name.first", "name.last"]} className="error" />
  </fieldset>
  <label>
    Date of Birth
    <Form.Field name="dateOfBirth" />
  </label>
  <Form.Message for="dateOfBirth" className="error" />
  <label>
    Favorite Color
    <Form.Field name="colorId" as="select">
      <option value={null}>Select a color...</option>
      <option value={0}>Red</option>
      <option value={1}>Yellow</option>
      <option value={2}>Blue</option>
      <option value={3}>other</option>
    </Form.Field>
  </label>
  <Form.Message for="colorId" className="error" />
  <Form.Submit type="submit">Submit</Form.Submit>
</Form>;

Schema

A schema is not strictly required, however describing form data with a schema offers many benefits that make their use worthwhile.

Schema provide an expressive language for describing validation at a field level as well as form-wide tests.
Schema provide type metadata that React Formal can use to simplify configuration. yup.array() fields are automatically render <select multiple>, yup.boolean()s render checkboxes, and so on
Schema allow encapsulating server serialization and business logic apart from your specific UI. Validation and transformations are not strictly tied to form input layout or UI means more maintainable, composable, and testable code.

Field Inference

A Field's schema provides runtime type information that can be used to help reduce boilerplate UI code. Field's will render the most appropriate native input for your field type (you can always override it).

const schema = yup.object({
  list: yup.array(),
  number: yup.number(),
  date: yup.date()
});

<Form schema={schema}>
  <label>
    A list
    <Form.Field name="list" />
  </label>
  <label>
    A number picker
    <Form.Field name="number" />
  </label>
  <label>
    A date picker
    <Form.Field name="date" />
  </label>
</Form>;

const schema = yup.object({
  list: yup.array(),
  number: yup.number(),
  date: yup.date()
});
<Form schema={schema}>
  <label>
    A list
    <Form.Field name="list" />
  </label>
  <label>
    A number picker
    <Form.Field name="number" />
  </label>
  <label>
    A date picker
    <Form.Field name="date" />
  </label>
</Form>;

Data Serialization

Schema can also do data sanitiation and transformation. When a Form is submitted the current value is passed through the schema a final time as a whole, the transformed value is what is passed back to the onSubmit handlers (you can override this behavior with strict).

const [submittedValue, setSubmittedValue] = useState({});
const schema = yup.object({
  slug: yup
    .string()
    .lowercase()
    .transform(value =>
      value
        .replace(/not/g, "")
        .trim()
        .replace(/\s+/g, "-")
    )
});

<Form
  schema={schema}
  defaultValue={{ slug: "Not a Good Slug" }}
  onSubmit={setSubmittedValue}
  className="lg:flex"
>
  <div className="lg:flex-2">
    <label>
      Slug (submit to see result)
      <Form.Field name="slug" readOnly />
    </label>
    <Form.Submit type="submit">Submit</Form.Submit>
  </div>
  <Result value={submittedValue} className="lg:ml-4 lg:mt-0" />
</Form>;

const [submittedValue, setSubmittedValue] = useState({});
const schema = yup.object({
  slug: yup
    .string()
    .lowercase()
    .transform(value =>
      value
        .replace(/not/g, "")
        .trim()
        .replace(/\s+/g, "-")
    )
});
<Form
  schema={schema}
  defaultValue={{ slug: "Not a Good Slug" }}
  onSubmit={setSubmittedValue}
  className="lg:flex"
>
  <div className="lg:flex-2">
    <label>
      Slug (submit to see result)
      <Form.Field name="slug" readOnly />
    </label>
    <Form.Submit type="submit">Submit</Form.Submit>
  </div>
  <Result value={submittedValue} className="lg:ml-4 lg:mt-0" />
</Form>;

API

import { Form } from 'react-formal';

abortEarly

Controls how errors are dealt with for field level validation. When set, the first validation error a field throws is returned instead of waiting for all validations to finish

type:boolean

as

A tag name or Component class the Form should render.

If null are false the form will simply render it's child. In this instance there must only be one child.

type:ReactElementTypenullfalse

default:'form'

children

type:ReactReactNode

className

type:string

context

yup schema context

type:Record<string, unknown>

debug

toggle debug mode, which console.warns validation errors

type:boolean

defaultErrors

type:Errors

default:ErrorUtils.EMPTY_ERRORS

defaultTouched

type:Touched

default:{}

defaultValue

type:Partial<TValue>

delay

Time in milliseconds that validations should be debounced. Reduces the amount of validation calls made at the expense of a slight delay. Helpful for performance.

type:number

default:300

errors

An object hash of field errors for the form. The object should be keyed with paths with the values being an array of errors or message objects. Errors can be left uncontrolled (use defaultErrors to set an initial value) or managed along with the onError callback. You can use any object shape you'd like for errors, as long as you provide the Form.Message component an extract prop that understands how to pull out the strings message. By default it understands strings and objects with a 'message' property.

<Form errors={{
 "name.first": [
   'First names are required',
   {
    message: "Names must be at least 2 characters long",
    type: 'min'
   }
 ],
}}/>

type:Errors

getter

A value getter function. getter is called with path and value and should return the plain javascript value at the path.

function(
 path: string,
 value: any,
): Object

type:(path: string, value: TValue) => any

default:formGetter

noValidate

Turns off input validation for the Form, value updates will continue to work.

type:boolean

onBeforeSubmit

Callback that is fired in response to a submit, before validation runs.

function onSubmit(formValue) {
  // do something with valid value
}

type:(data: BeforeSubmitData) => void

onChange

Callback that is called when the value prop changes.

function (
  value: any,
  updatedPaths: string[]
)

type:(input: TValue, changedPaths: string[]) => void

onError

Callback that is called when a validation error occurs. It is called with an errors object

const schema = yup.object({
  name: yup.string().required().min(15)
})

const [errors, setErrors] = useState({});

<Form
  schema={schema}
  errors={errors}
  onError={errors => {
    if (errors.name) {
      errors.name = 'hijacked!'
    }

    setErrors(errors)
}}>
   <label>
     Name
     <Form.Field name='name'/>
   </label>
  <Form.Message for='name' className="error" />

  <Form.Submit type='submit'>Submit</Form.Submit>
</Form>

const schema = yup.object({
  name: yup.string().required().min(15)
})
const [errors, setErrors] = useState({});
<Form
  schema={schema}
  errors={errors}
  onError={errors => {
    if (errors.name) {
      errors.name = 'hijacked!'
    }
    setErrors(errors)
}}>
   <label>
     Name
     <Form.Field name='name'/>
   </label>
  <Form.Message for='name' className="error" />
  <Form.Submit type='submit'>Submit</Form.Submit>
</Form>

type:(errors: Errors) => void

onInvalidSubmit

Callback that is fired when the native onSubmit event is triggered. Only relevant when the component prop renders a <form/> tag. onInvalidSubmit will trigger only if the form is invalid.

function onInvalidSubmit(errors){
  // do something with errors
}

type:(errors: Errors) => void

onReset

Callback that is fired in response to a form reset. onReset fires before the accompanying onChange.

function onReset() {
  // reset has been called
}

type:() => void

onSubmit

Callback that is fired in response to a submit, after validation runs for the entire form.

function onSubmit(formValue) {
  // do something with valid value
}

type:(validatedValue: InferType<TSchema>) => void

onSubmitFinished

type:(error: Error) => void

onTouch

Callback that is called when a field is touched. It is called with an touched object

type:(touched: Touched, changedPaths: string[]) => void

onValidate

Callback that is called whenever a validation is triggered. It is called before the validation is actually run.

function onValidate(event) {
  let { type, fields, args } = event
}

type:(data: ValidateData) => void

schema

A Yup schema that validates the Form value prop. Used to validate the form input values For more information about the yup api check out: https://github.com/jquense/yup/blob/master/README.md

type:{Schema}

setter

A value setter function. setter is called with path, the form value and the path value. The setter must return updated form value, which allows you to leave the original value unmutated.

The default implementation uses the react immutability helpers, letting you treat the form value as immutable.

function(
 path: string,
 formValue: any,
 pathValue: any
): Object

type:(path: string, value: TValue, fieldValue: any) => TValue

default:formSetter

strict

Validations will be strict, making no attempt to coarce input values to the appropriate type.

type:boolean

default:false

stripUnknown

type:boolean

submitForm

type:(input: TValue) => Promise<any>any

touched

An object hash of field paths and whether they have been "touched" yet

type:Touched

value

Form value object, can be left uncontrolled; use the defaultValue prop to initialize an uncontrolled form.

type:TValue

Form

#Overview

#Schema

#Field Inference

#Data Serialization

#API

#abortEarly

#as

#children

#className

#context

#debug

#defaultErrors

#defaultTouched

#defaultValue

#delay

#errors

#getter

#noValidate

#onBeforeSubmit

#onChange

#onError

#onInvalidSubmit

#onReset

#onSubmit

#onSubmitFinished

#onTouch

#onValidate

#schema

#setter

#strict

#stripUnknown

#submitForm

#touched

#value

Overview

Schema

Field Inference

Data Serialization

API

abortEarly

as

children

className

context

debug

defaultErrors

defaultTouched

defaultValue

delay

errors

getter

noValidate

onBeforeSubmit

onChange

onError

onInvalidSubmit

onReset

onSubmit

onSubmitFinished

onTouch

onValidate

schema

setter

strict

stripUnknown

submitForm

touched

value