function Example() {
  const [form, { message }] = useForm();

  return (
    <form>
-      <input {...conform.input(message.config)} />
+      <input {...conform.input(message)} />
      {message.error}
    </form>
  );

The submission.intent is now merged with submission.type to align with the intent button approach that are common in Remix. (#91)

export async function action({ request }: ActionArgs) {
    const formData = await request.formData();
    const submission = parse(formData);

    // The `submission.intent` is `submit` if the user click on the submit button with no specific intent (default)
    if (!submission.value || submission.intent !== 'submit') {
        return json(submission);
    }

    // ...
}

The validate and formatError helpers are replaced by a new parse helper, which can be used on both client and server side: (#92)

// The new `parse` helper can be treat as a replacement of the parse helper from `@conform-to/react`
import { parse } from '@conform-to/zod'; // or `@conform-to/yup`

const schema = z.object({ /* ... */ });

export async function action({ request }: ActionArgs) {
    const formData = await request.formData();
    const submission = parse(formData, {
        schema,
        
        // If you need to run async validation on the server
        async: true,
    });

    // `submission.value` is defined only if no error
    if (!submission.value || submission.intent !== 'submit') {
        return json(submission);
    }

    // ...
}

export default function Example() {
    const [form, fieldset] = useForm({
        onValidate({ formData }) {
            return parse(formData, { schema });
        },
        // ...
    });

    // ...
}

Redesigned the async validation setup with the VALIDATION_SKIPPED and VALIDATION_UNDEFINED message (#100)

import { conform, useForm } from '@conform-to/react';
import { parse } from '@conform-to/zod';
import { z } from 'zod';

// Instead of sharing a schema, we prepare a schema creator
function createSchema(
    intent: string,
    // Note: the constraints parameter is optional
    constraints: {
        isEmailUnique?: (email: string) => Promise<boolean>;
    } = {},
) {
    return z.object({
        name: z
            .string()
            .min(1, 'Name is required'),
        email: z
            .string()
            .min(1, 'Email is required')
            .email('Email is invalid')
            // We use `.superRefine` instead of `.refine` for better control 
            .superRefine((value, ctx) => {
                if (intent !== 'validate/email' && intent !== 'submit') {
                    // Validate only when necessary
                    ctx.addIssue({
                        code: z.ZodIssueCode.custom,
                        message: conform.VALIDATION_SKIPPED,
                    });
                } else if (typeof constraints.isEmailUnique === 'undefined') {
                    // Validate only if the constraint is defined
                    ctx.addIssue({
                        code: z.ZodIssueCode.custom,
                        message: conform.VALIDATION_UNDEFINED,
                    });
                } else {
                    // Tell zod this is an async validation by returning the promise
                    return constraints.isEmailUnique(value).then((isUnique) => {
                        if (isUnique) {
                            return;
                        }

                        ctx.addIssue({
                            code: z.ZodIssueCode.custom,
                            message: 'Email is already used',
                        });
                    });
                }
            }),
        title: z
            .string().min(1, 'Title is required')
            .max(20, 'Title is too long'),
    });
}

export let action = async ({ request }: ActionArgs) => {
    const formData = await request.formData();
    const submission = await parse(formData, {
        schema: (intent) =>
            // create the zod schema with the intent and constraint
            createSchema(intent, {
                async isEmailUnique(email) {
                    // ...
                },
            }),
        async: true,
    });

    return json(submission);
};

export default function EmployeeForm() {
    const lastSubmission = useActionData();
    const [form, { name, email, title }] = useForm({
        lastSubmission,
        onValidate({ formData }) {
            return parse(formData, {
                // Create the schema without any constraint defined
                schema: (intent) => createSchema(intent),
            });
        },
    });

    return (
        <Form method="post" {...form.props}>
            {/* ... */}
        </Form>
    );
}

The validation mode option is removed. Conform will now decide the validation mode based on whether onValidate is defined or not. (#95)

export default function Example() {
    const [form, fieldset] = useForm({
        // Server validation will be enabled unless the next 3 lines are uncommented
        // onValidate({ formData }) {
        //    return parse(formData, { schema });
        // },
    });

    // ...
}

The state option is now called lastSubmission on the useForm hook (#115)
The useControlledInput hook is removed, please use useInputEvent (#97)
The getFormElements and requestSubmit API are also removed (#110)

Improvements

Added multiple errors support (#96)

import { parse } from '@conform-to/zod';
import { z } from 'zod';

export async function action({ request }: ActionArgs) {
    const formData = await request.formData();
    const submission = parse(formData, {
        schema: z.object({
            // ...
            password: z
                .string()
                .min(10, 'The password should have minimum 10 characters')
                .refine(password => password.toLowerCase() === password, 'The password should have at least 1 uppercase character')
                .refine(password => password.toUpperCase() === password, 'The password should have at least 1 lowercase character')
        }),

        // Default to false if not specified
        acceptMultipleErrors({ name }) {
            return name === 'password';
        }
    });

    // ...
}

export default function Example() {
    const lastSubmission = useActionData();
    const [form, { password }] = useForm({
        lastSubmission,
    });

    return (
        <Form {...form.props}>
            { /* ... */ }
            <div>
                <label>Password</label>
                <input {...conform.input(password, { type: 'password' })} />
                <ul>
                    {password.errors?.map((error, i) => (
                        <li key={i}>{error}</li>
                    ))}
                </ul>
            </div>
            { /* ... */ }
        </Form>

    )
}

Simplified access to form attributes within the onSubmit handler (#99)

export default function Login() {
  const submit = useSubmit();
  const [form] = useForm({
    async onSubmit(event, { formData, method, action, encType }) {
      event.preventDefault();

      formData.set("captcha", await captcha());

      // Both method, action, encType are properly typed
      // to fullfill the types required by the submit function
      // with awareness on submitter attributes
      submit(formData, { method, action, encType });
    },
  });

  // ...
}

Introduced a new validateConstraint helper to fully utilize browser validation. Best suited for application built with react-router. (#89)

import { useForm, validateConstraint } from '@conform-to/react';
import { Form } from 'react-router-dom';

export default function SignupForm() {
    const [form, { email, password, confirmPassword }] = useForm({
        onValidate(context) {
            // This enables validating each field based on the validity state and custom cosntraint if defined
            return validateConstraint(
              ...context,
              constraint: {
                // Define custom constraint
                match(value, { formData, attributeValue }) {
                    // Check if the value of the field match the value of another field
                    return value === formData.get(attributeValue);
                },
            });
        }
    });

    return (
        <Form method="post" {...form.props}>
            <div>
                <label>Email</label>
                <input
                    name="email"
                    type="email"
                    required
                    pattern="[^@]+@[^@]+\\.[^@]+"
                />
                {email.error === 'required' ? (
                    <div>Email is required</div>
                ) : email.error === 'type' ? (
                    <div>Email is invalid</div>
                ) : null}
            </div>
            <div>
                <label>Password</label>
                <input
                    name="password"
                    type="password"
                    required
                />
                {password.error === 'required' ? (
                    <div>Password is required</div>
                ) : null}
            </div>
            <div>
                <label>Confirm Password</label>
                <input
                    name="confirmPassword"
                    type="password"
                    required
                    data-constraint-match="password"
                />
                {confirmPassword.error === 'required' ? (
                    <div>Confirm Password is required</div>
                ) : confirmPassword.error === 'match' ? (
                    <div>Password does not match</div>
                ) : null}
            </div>
            <button>Signup</button>
        </Form>
    );
}

Added support of aria-attributes on form.props (#114)
Fixed an issue with error not being caught on list validation, e.g. min / max (#75)
Conform will now focus on first invalid non button fields even when pressing enter (#109)

Docs

Fixed header spelling by @brandonpittman in #94

Full Changelog: https://github.com/edmundhung/conform/compare/v0.5.1...v0.6.0

Readme

Source

@conform-to/react

React adapter for conform

API Reference

useForm

By default, the browser calls the reportValidity() API on the form element when a submission is triggered. This checks the validity of all the fields and reports through the error bubbles.

This hook enhances the form validation behaviour by:

Enabling customizing validation logic.
Capturing error message and removes the error bubbles.
Preparing all properties required to configure the form elements.

import { useForm } from '@conform-to/react';

function LoginForm() {
  const [form, { email, password }] = useForm({
    /**
     * If the form id is provided, Id for label,
     * input and error elements will be derived.
     */
    id: undefined,

    /**
     * Define when the error should be reported initially.
     * Support "onSubmit", "onChange", "onBlur".
     *
     * Default to `onSubmit`.
     */
    initialReport: 'onBlur',

    /**
     * An object representing the initial value of the form.
     */
    defaultValue: undefined,

    /**
     * The last submission result from the server
     */
    lastSubmission: undefined,

    /**
     * An object describing the constraint of each field
     */
    constraint: undefined,

    /**
     * Enable native validation before hydation.
     *
     * Default to `false`.
     */
    fallbackNative: false,

    /**
     * Accept form submission regardless of the form validity.
     *
     * Default to `false`.
     */
    noValidate: false,

    /**
     * A function to be called when the form should be (re)validated.
     * Only sync validation is supported
     */
    onValidate({ form, formData }) {
      // ...
    },

    /**
     * The submit event handler of the form.
     */
    onSubmit(event, { formData, submission, action, encType, method }) {
      // ...
    },
  });

  // ...
}

What is `form.props`?

It is a group of properties required to hook into form events. They can also be set explicitly as shown below:

function RandomForm() {
  const [form] = useForm();

  return (
    <form
      ref={form.props.ref}
      id={form.props.id}
      onSubmit={form.props.onSubmit}
      noValidate={form.props.noValidate}
    >
      {/* ... */}
    </form>
  );
}

Does it work with custom form component like Remix Form?

Yes! It will fallback to native form submission as long as the submit event is not default prevented.

import { useFrom } from '@conform-to/react';
import { Form } from '@remix-run/react';

function LoginForm() {
  const [form] = useForm();

  return (
    <Form method="post" action="/login" {...form.props}>
      {/* ... */}
    </Form>
  );
}

useFieldset

This hook enables you to work with nested object by monitoring the state of each nested field and prepraing the config required.

import { useForm, useFieldset, conform } from '@conform-to/react';

interface Address {
  street: string;
  zipcode: string;
  city: string;
  country: string;
}

function Example() {
  const [form, { address }] = useForm<{ address: Address }>();
  const { city, zipcode, street, country } = useFieldset(
    form.ref,
    address,
  );

  return (
    <form {...form.props}>
      <fieldset>
        <legned>Address</legend>
        <input {...conform.input(street)} />
        <div>{street.error}</div>
        <input {...conform.input(zipcode)} />
        <div>{zipcode.error}</div>
        <input {...conform.input(city)} />
        <div>{city.error}</div>
        <input {...conform.input(country)} />
        <div>{country.error}</div>
      </fieldset>
      <button>Submit</button>
    </form>
  );
}

If you don't have direct access to the form ref, you can also pass a fieldset ref.

import { type FieldConfig, useFieldset } from '@conform-to/react';
import { useRef } from 'react';

function Fieldset(config: FieldConfig<Address>) {
  const ref = useRef<HTMLFieldsetElement>(null);
  const { city, zipcode, street, country } = useFieldset(ref, config);

  return <fieldset ref={ref}>{/* ... */}</fieldset>;
}

Why does `useFieldset` require a ref object of the form or fieldset?

conform utilises the DOM as its context provider / input registry, which maintains a link between each input / button / fieldset with the form through the form property. The ref object allows it to restrict the scope to form elements associated to the same form only.

function ExampleForm() {
  const formRef = useRef();
  const inputRef = useRef();

  useEffect(() => {
    // Both statements will log `true`
    console.log(formRef.current === inputRef.current.form);
    console.log(formRef.current.elements.namedItem('title') === inputRef.current)
  }, []);

  return (
    <form ref={formRef}>
      <input ref={inputRef} name="title">
    </form>
  );
}

useFieldList

This hook enables you to work with array and support the list intent button builder to modify a list. It can also be used with useFieldset for nested list at the same time.

import { useForm, useFieldList, list } from '@conform-to/react';

/**
 * Consider the schema as follow:
 */
type Schema = {
  items: string[];
};

function Example() {
  const [form, { items }] = useForm<Schema>();
  const itemsList = useFieldList(form.ref, items);

  return (
    <fieldset ref={ref}>
      {itemsList.map((item, index) => (
        <div key={item.key}>
          {/* Setup an input per item */}
          <input {...conform.input(item)} />

          {/* Error of each item */}
          <span>{item.error}</span>

          {/* Setup a delete button (Note: It is `items` not `item`) */}
          <button {...list.remove(items.name, { index })}>Delete</button>
        </div>
      ))}

      {/* Setup a button that can append a new row with optional default value */}
      <button {...list.append(items.name, { defaultValue: '' })}>add</button>
    </fieldset>
  );
}

useInputEvent

It returns a ref object and a set of helpers that dispatch corresponding dom event.

import { useForm, useInputEvent } from '@conform-to/react';
import { Select, MenuItem } from '@mui/material';
import { useState, useRef } from 'react';

function MuiForm() {
  const [form, { category }] = useForm();
  const [value, setValue] = useState(category.defaultValue ?? '');
  const [ref, control] = useInputEvent({
    onReset: () => setValue(category.defaultValue ?? ''),
  });
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <form {...form.props}>
      {/* Render a shadow input somewhere */}
      <input
        ref={ref}
        {...conform.input(category, { hidden: true })}
        onChange={(e) => setValue(e.target.value)}
        onFocus={() => inputRef.current?.focus()}
      />

      {/* MUI Select is a controlled component */}
      <TextField
        label="Category"
        inputRef={inputRef}
        value={value}
        onChange={control.change}
        onBlur={control.blur}
        select
      >
        <MenuItem value="">Please select</MenuItem>
        <MenuItem value="a">Category A</MenuItem>
        <MenuItem value="b">Category B</MenuItem>
        <MenuItem value="c">Category C</MenuItem>
      </TextField>
    </form>
  );
}

conform

It provides several helpers to remove the boilerplate when configuring a form control and derives attributes for accessibility concerns and helps focus management.

You can also create a wrapper on top if you need to integrate with custom input component.

Before:

import { useForm } from '@conform-to/react';

function Example() {
  const [form, { title, description, category }] = useForm();

  return (
    <form {...form.props}>
      <input
        type="text"
        name={title.name}
        form={title.form}
        defaultValue={title.defaultValue}
        requried={title.required}
        minLength={title.minLength}
        maxLength={title.maxLength}
        min={title.min}
        max={title.max}
        multiple={title.multiple}
        pattern={title.pattern}
      />
      <textarea
        name={description.name}
        form={description.form}
        defaultValue={description.defaultValue}
        requried={description.required}
        minLength={description.minLength}
        maxLength={description.maxLength}
      />
      <select
        name={category.name}
        form={category.form}
        defaultValue={category.defaultValue}
        requried={category.required}
        multiple={category.multiple}
      >
        {/* ... */}
      </select>
    </form>
  );
}

After:

import { useForm, conform } from '@conform-to/react';

function Example() {
  const [form, { title, description, category }] = useForm();

  return (
    <form {...form.props}>
      <input {...conform.input(title, { type: 'text' })} />
      <textarea {...conform.textarea(description)} />
      <select {...conform.select(category)}>{/* ... */}</select>
    </form>
  );
}

parse

It parses the formData based on the naming convention with the validation result from the resolver.

import { parse } from '@conform-to/react';

const formData = new FormData();
const submission = parse(formData, {
  resolve({ email, password }) {
    const error: Record<string, string> = {};

    if (typeof email !== 'string') {
      error.email = 'Email is required';
    } else if (!/^[^@]+@[^@]+$/.test(email)) {
      error.email = 'Email is invalid';
    }

    if (typeof password !== 'string') {
      error.password = 'Password is required';
    }

    if (error.email || error.password) {
      return { error };
    }

    return {
      value: { email, password },
    };
  },
});

validateConstraint

This enable Constraint Validation with ability to enable custom constraint using data-attribute and customizing error messages. By default, the error message would be the attribute that triggered the error (e.g. required / type / 'minLength' etc).

import { useForm, validateConstraint } from '@conform-to/react';
import { Form } from 'react-router-dom';

export default function SignupForm() {
    const [form, { email, password, confirmPassword }] = useForm({
        onValidate(context) {
            // This enables validating each field based on the validity state and custom cosntraint if defined
            return validateConstraint(
              ...context,
              constraint: {
                // Define custom constraint
                match(value, { formData, attributeValue }) {
                    // Check if the value of the field match the value of another field
                    return value === formData.get(attributeValue);
                },
            });
        }
    });

    return (
        <Form method="post" {...form.props}>
            <div>
                <label>Email</label>
                <input
                    name="email"
                    type="email"
                    required
                    pattern="[^@]+@[^@]+\\.[^@]+"
                />
                {email.error === 'required' ? (
                    <div>Email is required</div>
                ) : email.error === 'type' ? (
                    <div>Email is invalid</div>
                ) : null}
            </div>
            <div>
                <label>Password</label>
                <input
                    name="password"
                    type="password"
                    required
                />
                {password.error === 'required' ? (
                    <div>Password is required</div>
                ) : null}
            </div>
            <div>
                <label>Confirm Password</label>
                <input
                    name="confirmPassword"
                    type="password"
                    required
                    data-constraint-match="password"
                />
                {confirmPassword.error === 'required' ? (
                    <div>Confirm Password is required</div>
                ) : confirmPassword.error === 'match' ? (
                    <div>Password does not match</div>
                ) : null}
            </div>
            <button>Signup</button>
        </Form>
    );
}

list

It provides serveral helpers to configure an intent button for modifying a list.

import { list } from '@conform-to/react';

function Example() {
  return (
    <form>
      {/* To append a new row with optional defaultValue */}
      <button {...list.append('name', { defaultValue })}>Append</button>

      {/* To prepend a new row with optional defaultValue */}
      <button {...list.prepend('name', { defaultValue })}>Prepend</button>

      {/* To remove a row by index */}
      <button {...list.remove('name', { index })}>Remove</button>

      {/* To replace a row with another defaultValue */}
      <button {...list.replace('name', { index, defaultValue })}>
        Replace
      </button>

      {/* To reorder a particular row to an another index */}
      <button {...list.reorder('name', { from, to })}>Reorder</button>
    </form>
  );
}

validate

It returns the properties required to configure an intent button for validation.

import { validate } from '@conform-to/react';

function Example() {
  return (
    <form>
      {/* To validate a single field by name */}
      <button {...validate('email')}>Validate email</button>

      {/* To validate the whole form */}
      <button {...validate()}>Validate</button>
    </form>
  );
}

requestIntent

It lets you trigger an intent without requiring users to click on a button. It supports both list and validate intent.

import {
  useForm,
  useFieldList,
  conform,
  list,
  requestIntent,
} from '@conform-to/react';
import DragAndDrop from 'awesome-dnd-example';

export default function Todos() {
  const [form, { tasks }] = useForm();
  const taskList = useFieldList(form.ref, tasks);

  const handleDrop = (from, to) =>
    requestIntent(form.ref.current, list.reorder({ from, to }));

  return (
    <form {...form.props}>
      <DragAndDrop onDrop={handleDrop}>
        {taskList.map((task, index) => (
          <div key={task.key}>
            <input {...conform.input(task)} />
          </div>
        ))}
      </DragAndDrop>
      <button>Save</button>
    </form>
  );
}

isFieldElement

This is an utility for checking if the provided element is a form element (input / select / textarea or button) which also works as a type guard.

function Example() {
  return (
    <form
      onFocus={(event) => {
        if (isFieldElement(event.target)) {
          // event.target is now considered one of the form elements type
        }
      }}
    >
      {/* ... */}
    </form>
  );
}

Keywords

FAQs

What is @conform-to/react?

Is @conform-to/react popular?

Is @conform-to/react well maintained?

Last updated on 11 Mar 2023

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket

@conform-to/react

.css-1z04cui{margin-bottom:var(--chakra-space-4);font-size:var(--chakra-fontSizes-md);}v0.6.0

Breaking Changes

Improvements

Docs

@conform-to/react

API Reference

useForm

useFieldset

useFieldList

useInputEvent

conform

parse

validateConstraint

list

validate

requestIntent

isFieldElement

Keywords

v0.6.0