parseSubmission

The parseSubmission function is part of Conform's future export. These APIs are experimental and may change in minor versions. Learn more

A utility function that parses FormData or URLSearchParams into a structured submission object that includes a nested payload with intent and field names extracted. Field names are parsed using these conventions:

name → { name: "value" }
object.property → { object: { property: "value" } }
array[0] → { array: ["value"] }
items[] → { items: ["value1", "value2"] }

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

const submission = parseSubmission(formData, options);

#Parameters

`formData: FormData | URLSearchParams`

The form data to parse, typically from:

Request: await request.formData() or new URLSearchParams(request.url)
Form element: new FormData(form)
URL: new URLSearchParams(searchString)

`options.intentName?: string`

The name of the submit button field that indicates the submission intent. Defaults to __INTENT__.

`options.skipEntry?: (name: string) => boolean`

A function to exclude specific form fields from being parsed. Return true to skip the entry.

#Returns

A Submission object containing:

`payload: Record<string, unknown>`

The parsed form values structured as nested objects and arrays based on field naming conventions.

`fields: string[]`

List of field names that were present in the form data.

`intent: string | null`

The submission intent (button value) if an intent button was found, otherwise null.

#Example

React Router Action function

1export async function action({ request }: Route.ActionArgs) {
2  const formData = await request.formData();
3  const submission = parseSubmission(formData);
4
5  // validate and process submission...
6}
7
8// You can also do this with clientAction
9export async function clientAction({ request }: Route.ActionArgs) {
10  const formData = await request.formData();
11  const submission = parseSubmission(formData);
12
13  // validate and process submission...
14}

Next.js Server Action function

1export async function createUser(prevState: unknown, formData: FormData) {
2  'use server';
3
4  const submission = parseSubmission(formData);
5
6  // validate and save user...
7}

Client-side live value subscription

1function MyForm() {
2  const formRef = useRef<HTMLFormElement>(null);
3
4  // Subscribe to live form data changes
5  const payload = useFormData(formRef, (formData) =>
6    formData ? parseSubmission(formData).payload : null,
7  );
8
9  return (
10    <form ref={formRef}>
11      <input name="user.name" />
12      <input name="user.email" />
13
14      {/* Show live parsed data */}
15      <pre>{JSON.stringify(payload, null, 2)}</pre>
16    </form>
17  );
18}