@shopify/react-form/README.md

Manage react forms tersely and safely-typed with no magic using React hooks.

# `@shopify/react-form`

[![Build Status](https://travis-ci.org/Shopify/quilt.svg?branch=master)](https://travis-ci.org/Shopify/quilt)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md) [![npm version](https://badge.fury.io/js/%40shopify%2Freact-form.svg)](https://badge.fury.io/js/%40shopify%2Freact-form.svg) [![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@shopify/react-form.svg)](https://img.shields.io/bundlephobia/minzip/@shopify/react-form.svg)

Manage react forms tersely and safely-typed with no magic using React hooks. Build up your form logic by combining hooks yourself, or take advantage of the smart defaults provided by the powerful `useForm` hook.

## Table of contents

1. [Installation](#installation)
1. [Usage](#usage)
   1. [Quickstart](#quickstart)
   1. [Composition](#composition)
1. [API](#api)
   1. [Hooks](#hooks)
      1. [useField](#usefield)
      1. [useList](#uselist)
      1. [useForm](#useform)
      1. [useValidateAll](#usevalidateall)
      1. [useDirty](#usedirty)
      1. [useReset](#usereset)
      1. [useSubmit](#usesubmit)
      1. [useErrorPropagation](#useerrorpropagation)
   1. [Validation](#validation)
      1. [inline](#validation)
      1. [multiple](#validation)
      1. [dependencies](#validation)
      1. [built-in](#validation)
      1. [validator](#validation)
1. [FAQ](#faq)

## Installation

```bash
$ yarn add @shopify/react-form
```

## Usage

### Quickstart

This package exports a variety of hooks for all things form state, but the quickest way to get up and running is with the hooks `useForm` and `useField`.

```tsx
import {useForm, useField} from '@shopify/react-form';
```

By passing `useForm` a dictionary of field objects generated by `useField` calls, you can build out a fully featured form with minimal effort.

```tsx
import * as React from 'react';
import {useField, useForm} from '@shopify/react-form';

function MyComponent() {
  const {fields, submit, submitting, dirty, reset, submitErrors} = useForm({
    fields: {
      title: useField('some default title'),
    },
    onSubmit: fieldValues => {
      return {status: 'fail', errors: [{message: 'bad form data'}]};
    },
  });

  const loading = submitting ? <p className="loading">loading...</p> : null;
  const errors =
    submitErrors.length > 0 ? (
      <p className="error">{submitErrors.join(', ')}</p>
    ) : null;

  return (
    <form onSubmit={submit}>
      {loading}
      {errors}
      <div>
        <label htmlFor="title">
          Title
          <input
            id="title"
            name="title"
            value={title.value}
            onChange={title.onChange}
            onBlur={title.onBlur}
          />
        </label>
        {title.error && <p className="error">{title.error}</p>}
      </div>
      <button type="button" disabled={!dirty} onClick={reset}>
        Reset
      </button>
      <button type="submit" disabled={!dirty} onclick={submit}>
        Submit
      </button>
    </form>
  );
}
```

The hooks provided here also work swimmingly with [`@shopify/polaris`](https://polaris.shopify.com/).

```tsx
import * as React from 'react';
import {useField, useForm, notEmpty, lengthMoreThan} from '@shopify/react-form';

import {
  AppProvider,
  Page,
  Layout,
  FormLayout,
  Form,
  Card,
  TextField,
  ContextualSaveBar,
  Frame,
  Banner,
} from '@shopify/polaris';

export default function MyComponent() {
  const {fields, submit, submitting, dirty, reset, submitErrors} = useForm({
    fields: {
      title: useField({
        value: '',
        validates: [
          notEmpty('Title is required'),
          lengthMoreThan(3, 'Title must be more than 3 characters'),
        ],
      }),
      description: useField(''),
    },
    async onSubmit(form) {
      const remoteErrors = []; // your API call goes here
      if (remoteErrors.length > 0) {
        return {status: 'fail', errors: remoteErrors};
      }

      return {status: 'success'};
    },
  });

  const contextBar = dirty ? (
    <ContextualSaveBar
      message="Unsaved product"
      saveAction={{
        onAction: submit,
        loading: submitting,
        disabled: false,
      }}
      discardAction={{
        onAction: reset,
      }}
    />
  ) : null;

  const errorBanner =
    submitErrors.length > 0 ? (
      <Layout.Section>
        <Banner status="critical">
          <p>There were some issues with your form submission:</p>
          <ul>
            {submitErrors.map(({message}, index) => {
              return <li key={`${message}${index}`}>{message}</li>;
            })}
          </ul>
        </Banner>
      </Layout.Section>
    ) : null;

  return (
    <Frame>
      <Form onSubmit={submit}>
        <Page title="New Product">
          {contextBar}
          <Layout>
            {errorBanner}
            <Layout.Section>
              <Card sectioned>
                <FormLayout>
                  <TextField label="Title" {...fields.title} />
                  <TextField
                    multiline
                    label="Description"
                    {...fields.description}
                  />
                </FormLayout>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </Form>
    </Frame>
  );
}
```

### Composition

`useForm` gives us a lot in a small package, but one of the main benefits of hooks is composition. If we prefer, we can build our pages with much more granular use of hooks. This is especially valuable if you only need some of the behaviours of `useForm`, or need some aspect of the state to be managed differently.

```tsx
import * as React from 'react';
import {
  useField,
  useReset,
  useDirty,
  useSubmit,
  notEmpty,
  lengthMoreThan,
} from '@shopify/react-form';

import {
  AppProvider,
  Page,
  Layout,
  FormLayout,
  Form,
  Card,
  TextField,
  ContextualSaveBar,
  Frame,
  Banner,
} from '@shopify/polaris';

export default function MyComponent() {
  const title = useField({
    value: '',
    validates: [
      notEmpty('Title is required'),
      lengthMoreThan(3, 'Title must be more than 3 characters'),
    ],
  });
  const description = useField('');
  const fields = {title, description};

  // track whether any field has been changed from its initial values
  const dirty = useDirty(fields);

  // generate a reset callback
  const reset = useReset(fields);

  // handle submission state
  const {submit, submitting, errors, setErrors} = useSubmit(fieldValues => {
    const remoteErrors = []; // your API call goes here
    if (remoteErrors.length > 0) {
      return {status: 'fail', errors: remoteErrors};
    }

    return {status: 'success'};
  }, fields);

  // propagate submit errors back to the fields
  useErrorPropagation(fields, errors);

  const contextBar = dirty && (
    <ContextualSaveBar
      message="Unsaved product"
      saveAction={{
        onAction: submit,
        loading: submitting,
        disabled: false,
      }}
      discardAction={{
        onAction: reset,
      }}
    />
  );

  const errorBanner = errors.length > 0 && (
    <Layout.Section>
      <Banner status="critical">
        <p>There were some issues with your form submission:</p>
        <ul>
          {errors.map(({message}, index) => {
            return <li key={`${message}${index}`}>{message}</li>;
          })}
        </ul>
      </Banner>
    </Layout.Section>
  );

  return (
    <Frame>
      <Form onSubmit={submit}>
        <Page title="New Product">
          {contextBar}
          <Layout>
            {errorBanner}
            <Layout.Section>
              <Card sectioned>
                <FormLayout>
                  <TextField label="Title" {...fields.title} />
                  <TextField
                    multiline
                    label="Description"
                    {...fields.description}
                  />
                </FormLayout>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </Form>
    </Frame>
  );
}
```

## API

This section details the individual functions exported by `@shopify-react-form`. For more detailed typing information see the `.d.ts` files.

### Hooks

#### `useField()`

A custom hook for handling the state and validations of an input field.

##### Signature

```tsx
const field = useField(config, validationDependencies);
```

###### Parameters:

- `config`, The default value of the input, or a configuration object specifying both the value and validation config.
- `validationDependencies`, An optional array of values for determining when to regenerate the field's validation callbacks. Any value that is referenced by a validator other than those passed into it should be included.

###### Return value:

A `Field` object representing the state of your input. It also includes functions to manipulate that state. Generally,ou will want to pass these callbacks down to the component or components representing your input.

##### Examples

In its simplest form `useField` can be called with a single parameter for the default value of the field.

```tsx
const field = useField('default value');
```

You can also pass a more complex configuration object specifying a validation function.

```tsx
const field = useField({
  value: someRemoteData.title,
  validates: title => {
    if (title.length > 3) {
      return 'Title must be longer than three characters';
    }
  },
});
```

You may also pass multiple validators.

```tsx
const field = useField({
  value: someRemoteData.title,
  validates: [
    title => {
      if (title.length > 3) {
        return 'Title must be longer than three characters';
      }
    },
    title => {
      if (!title.includes('radical')) {
        return 'Only radical items are allowed';
      }
    },
  ],
});
```

Generally, you will want to use the object returned from `useField` to handle state for exactly one form input.

```tsx
const field = useField('default value');

const fieldError = field.error ? <p>{field.error}</p> : null;

return (
  <div>
    <label htmlFor="test-field">
      Test field{' '}
      <input
        id="test-field"
        name="test-field"
        value={field.value}
        onChange={field.onChange}
        onBlur={field.onBlur}
      />
    </label>
    {fieldError}
  </div>
);
```

If using `@shopify/polaris` or other custom components that support `onChange`, `onBlur`, `value`, and `error` props then
you can accomplish the above more tersely by using the ES6 spread `...` operator.

```tsx
const title = useField('default title');
return <TextField label="Title" {...title} />;
```

##### Remarks

**Reinitialization:** If the `value` property of the field configuration changes between calls to `useField`, the field will be reset to use it as its new default value.

**Imperative methods:** The returned `Field` object contains a number of methods used to imperatively alter its state. These should only be used as escape hatches where the existing hooks and components do not make your life easy, or to build new abstractions in the same vein as `useForm`, `useSubmit` and friends.

#### `useList()`

A custom hook for handling the state and validations of fields for a list of objects.

##### Signature

```tsx
const fields = useList(config, validationDependencies);
```

###### Parameters:

- `config`, A configuration object specifying both the value and validation config.
- `validationDependencies`, An array of dependencies to use to decide when to regenerate validators.

###### Return value:

A list of dictionaries of `Field` objects representing the state of your input. It also includes functions to manipulate that state. Generally, you will want to pass these callbacks down to the component or components representing yournput.

##### Examples

In its simplest form `useList` can be called with a single parameter with the list to derive default values and structure from.

```tsx
const field = useList([
  {title: '', description: ''},
  {title: '', description: ''},
]);
```

You can also pass a more complex configuration object specifying a validation dictionary.

```tsx
const field = useList({
  list: [{title: '', description: ''}, {title: '', description: ''}],
  validates: {
    title: title => {
      if (title.length > 3) {
        return 'Title must be longer than three characters';
      }
    },
    description: description => {
      if (description === '') {
        return 'Description is required!';
      }
    },
  },
});
```

Generally, you will want to use the list returned from `useList` by looping over it in your JSX.

```tsx
function MyComponent() {
  const variants = useList([
    {title: '', description: ''},
    {title: '', description: ''},
  ]);

  return (
    <ul>
      {variants.map((fields, index) => (
        <li key={index}>
          <label htmlFor={`title-${index}`}>
            title{' '}
            <input
              id={`title-${index}`}
              name={`title-${index}`}
              value={fields.title.value}
              onChange={fields.title.onChange}
              onBlur={fields.title.onBlur}
            />
          </label>
          {field.title.error && <p>{field.title.error}</p>}
          <label htmlFor={`description-${index}`}>
            description{' '}
            <input
              id={`description-${index}`}
              name={`description-${index}`}
              value={fields.description.value}
              onChange={fields.description.onChange}
              onBlur={fields.description.onBlur}
            />
          </label>
          {field.description.error && <p>{field.description.error}</p>}
        </li>
      ))}
    </ul>
  );
}
```

If using `@shopify/polaris` or other custom components that support `onChange`, `onBlur`, `value`, and `error` props then you can accomplish the above more tersely by using the ES6 spread `...` operator.

```tsx
function MyComponent() {
  const variants = useList([
    {title: '', description: ''},
    {title: '', description: ''},
  ]);

  return (
    <ul>
      {variants.map((fields, index) => (
        <li key={index}>
          <TextField label="title" name={`title${index}`} {...fields.title} />
          <TextField
            label="description"
            id={`description${index}`}
            {...fields.description}
          />
        </li>
      ))}
    </ul>
  );
}
```

##### Remarks

**Reinitialization:** If the `list` property of the field configuration changes between calls to `useList`, the field will be reset to use it as its new default value.

**Imperative methods:** The returned `Field` objects contains a number of methods used to imperatively alter their state. These should only be used as escape hatches where the existing hooks and components do not make your life easy, or to build new abstractions in the same vein as `useForm`, `useSubmit` and friends.

#### `useForm()`

A custom hook for managing the state of an entire form. `useForm` wraps up many of the other hooks in this package in one API, and when combined with `useField` and `useList`, allows you to easily build complex forms with smart defaults for common cases.

##### Signature

```tsx
const form = useForm(config);
```

###### Parameters:

- `config`, An object has the following fields:

  - `fields`, A dictionary of `Field` objects, dictionaries of `Field` objects, and lists of dictionaries of `Field` objects. Generally, you'll want these to be generated by the other hooks in this package, either `useField` or `useList`. This will be returned back out as the `fields` property of the return value.
  - `onSubmit`, An async function to handle submission of the form. If this function returns an object of `{state: 'fail', error: FormError[]}` then the submission is considered a failure. Otherwise, it should return an object with `{state: 'success'}` and the submission will be considered a success. `useForm` will also call all client-side validation methods for the fields passed to it. The `onSubmit` handler will not be called if client validations fails.

###### Return value:

An object representing the current state of the form, with imperative methods to reset, submit, and validate. Generally, the returned properties correspond 1:1 with the specific hook for their functionality.

#### Examples

`useForm` wraps one or more fields and return an object with all of the fields you need to manage a form.

```tsx
import * as React from 'react';
import {useField, useForm} from '@shopify/react-form';

function MyComponent() {
  const {fields, submit, submitting, dirty, reset, submitErrors} = useForm({
    fields: {
      title: useField('some default title'),
    },
    onSubmit: fieldValues => {
      return {status: 'fail', errors: [{message: 'bad form data'}]};
    },
  });

  const loading = submitting ? <p className="loading">loading...</p> : null;

  const submitErrorContent =
    submitErrors.length > 0 ? (
      <p className="error">{submitErrors.join(', ')}</p>
    ) : null;

  const titleError = title.error ? (
    <p className="error">{title.error}</p>
  ) : null;

  return (
    <form onSubmit={submit}>
      {loading}
      {submitErrorContent}
      <div>
        <label for="title">Title</label>
        <input
          id="title"
          name="title"
          value={title.value}
          onChange={title.onChange}
          onBlur={title.onBlur}
        />
        {titleError}
      </div>
      <button disabled={!dirty} onClick={reset}>
        Reset
      </button>
      <button type="submit" disabled={!dirty}>
        Submit
      </button>
    </form>
  );
}
```

As with `useField` and `useList`, `useForm` plays nicely out of the box with `@shopify/polaris`.

```tsx
import * as React from 'react';
import {
  Page,
  TextField,
  FormLayout,
  Card,
  Layout,
  Form,
  ContextualSaveBar,
  Frame,
  Banner,
} from '@shopify/polaris';
import {useField, useForm} from '@shopify/react-form';

function MyComponent() {
  const {fields, submit, submitting, dirty, reset, submitErrors} = useForm({
    fields: {
      title: useField('some default title'),
      description: useField('some default description'),
    },
    onSubmit: fieldValues => {
      return {status: 'fail', errors: [{message: 'bad form data'}]};
    },
  });

  const contextBar = dirty ? (
    <ContextualSaveBar
      message="New product"
      saveAction={{
        onAction: submit,
        loading: submitting,
        disabled: false,
      }}
      discardAction={{
        onAction: reset,
      }}
    />
  ) : null;

  const errorBanner =
    submitErrors.length > 0 ? (
      <Layout.Section>
        <Banner status="critical">
          <p>There were some issues with your form submission:</p>
          <ul>
            {submitErrors.map(({message}, index) => {
              return <li key={`${message}${index}`}>{message}</li>;
            })}
          </ul>
        </Banner>
      </Layout.Section>
    ) : null;

  return (
    <Frame>
      <Form onSubmit={submit}>
        <Page title={pageTitle}>
          {contextBar}
          <Layout>
            {errorBanner}
            <Layout.Section>
              <Card>
                <Card.Section>
                  <FormLayout>
                    <TextField label="Title" {...fields.title} />
                    <TextField
                      multiline
                      label="Description"
                      {...fields.description}
                    />
                  </FormLayout>
                </Card.Section>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </Form>
    </Frame>
  );
}
```

You can also configure fields ahead of time and pass them in to `useForm` afterwards. This is useful when you need one field to depend upon another for validation.

```tsx
import * as React from 'react';
import {
  Page,
  TextField,
  FormLayout,
  Card,
  Layout,
  Form,
  ContextualSaveBar,
  Frame,
  Banner,
} from '@shopify/polaris';
import {useField, useForm} from '@shopify/react-form';

function MyComponent() {
  const title = useField('');
  const price = useField(
    {
      value: '0.00',
      validates: value => {
        if (title.value.includes('expensive') && parseFloat(value) < 1000) {
          return 'Expensive items must cost more than 1000 dollars';
        }
      },
    },
    [title.value],
  );

  const {submit, submitting, dirty, reset, submitErrors} = useForm({
    fields: {title, description},
    onSubmit: fieldValues => {
      return {status: 'fail', errors: [{message: 'bad form data'}]};
    },
  });

  const contextBar = dirty ? (
    <ContextualSaveBar
      message="New product"
      saveAction={{
        onAction: submit,
        loading: submitting,
        disabled: false,
      }}
      discardAction={{
        onAction: reset,
      }}
    />
  ) : null;

  const errorBanner =
    submitErrors.length > 0 ? (
      <Layout.Section>
        <Banner status="critical">
          <p>There were some issues with your form submission:</p>
          <ul>
            {submitErrors.map(({message}, index) => {
              return <li key={`${message}${index}`}>{message}</li>;
            })}
          </ul>
        </Banner>
      </Layout.Section>
    ) : null;

  return (
    <Frame>
      <Form onSubmit={submit}>
        <Page title={pageTitle}>
          {contextBar}
          <Layout>
            {errorBanner}
            <Layout.Section>
              <Card>
                <Card.Section>
                  <FormLayout>
                    <TextField label="Title" {...title} />
                    <TextField type="number" label="Price" {...price} />
                  </FormLayout>
                </Card.Section>
              </Card>
            </Layout.Section>
          </Layout>
        </Page>
      </Form>
    </Frame>
  );
}
```

##### Remarks

- **Building your own:** Internally, `useForm` is a convenience wrapper over `useDirty`, `useReset`, `useValidateAll`, `useSubmit`, and `useErrorPropagation`.If you only need some of its functionality, consider building a custom hook combining a subset of them.
- **Subforms:** You can have multiple `useForm`s wrapping different subsets of a group of fields. Using this you can submit subsections of the form independently and have all the error and dirty tracking logic "just work" together.

#### useSubmit

#### useValidateAll

#### useDirty

#### useReset

#### useSubmit

#### useErrorPropagation

Docs for these standalone hooks are coming soon. For now check out the `.d.ts` files for the API.

### Validation

Detailed validation docs are coming soon. For now check out the `.d.ts` files for the API.

## FAQ

**Q: Why yet another form library? Why not just include a hook version in `@shopify/react-form-state`?**
**A:** It turns out that hooks enable a much more extensible and composable paradigm than render props did. they also have some limitations that the render prop API does not. As such its difficult to build the best API we can for a hooks world and still have it match up to the old monolithic `<FormState />` model. Since we use `<FormState />` in production and will need to keep it around in maintenance mode for the foreseeable future, it makes sense to have this library available as its own import. Apart from the clean composability of hooks, the rationale otherwise remains much the same as [`<FormState />`'s](https://github.com/Shopify/quilt/blob/master/packages/react-form-state/docs/FAQ.md)

**Q: When should I use `<FormState />` from `@shopify/react-form-state` instead of this?**
**A:** `@shopify/react-form-state` is now in maintenance mode only as of the release of this library. That means you're encouraged to use this library for any new work.

**Q: How can I revalidate fields when a different field changes?**
**A:** Part of the fun of hooks is how easy it is to compose different ones together. Since our fields All have `runValidation` methods, you can easily use the built in `useEffect` hook to invoke a field's validation whenever any arbitrary value is changed.

```tsx
import * as React from 'react';
import {TextField} from '@shopify/polaris';
import {useField, useForm} from '@shopify/react-form';

function MyForm() {
  const title = useField({
    value: '',
  });

  const price = useField(
    {
      value: '2.00',
      validates: value => {
        if (title.value.includes('expensive') && parseFloat(value) < 1000) {
          return 'Expensive items must be at least 1000 dollars.';
        }
      },
    },
    [title.value],
  );

  // whenever title changes we run the validator
  React.useEffect(price.runValidation, [title.value]);

  return (
    <div>
      <TextField {...title} />
      <TextField {...price} />
    </div>
  );
}
```

**Q: I want to use this in a class component, how can I?**
**A:** The short answer is you can't. The long answer is with the magic of components. You can create a functional component that wraps your form hooks and calls a render prop with the generated fields. This approximates a component based API, and is more flexible to your specific needs than trying to have a monolithic version available as part of the library.

```tsx
import * as React from 'react';
import {useField, useForm} from '@shopify/react-form';

function ProductForm({children, data}) {
  const title = useField(data.title);
  const description = useField(data.description);

  const form = useForm({
    title,
    description,
  });

  return <form onSubmit={form.submit}>{children(form)}</form>;
}
```

**Q: I want to dynamically change how many fields I render, how can I do that?**
**A:** It's tough to do this without breaking the rules of hooks. A possible solution is building a component encapsulating your hook calls, such as above, and then using a `key` to reset it when you need to. Another is 'faking' it by simply not rendering all of your fields despite always initializing the same number. Finally, you could build a custom reducer-based hook similar to `useList` that can support adding and removing fields dynamically. As long as it returns `Field` objects matching the API that the hooks in this library do, you will be able to use it with `useForm` and friends just fine.

**Q: How come {Feature X} is not supported?**
**A:** If you feel strongly about any features which are not part of this library, please open an issue or pull request.