Form Data Helpers

Form data helpers provide utilities for parsing HTML form data and extracting validation error messages, with full support for bracket notation to handle complex nested structures.

parseFormData

Parses HTML form data using bracket notation to deserialize complex nested objects and arrays.

import { function parseFormData(form: FormData): any
Parse a form data with [bracket notation](https://orpc.dev/docs/openapi/bracket-notation) syntax
@example```ts
const form = new FormData()
form.append('a', '1')
form.append('user[name]', 'John')
form.append('user[age]', '20')
form.append('user[friends][]', 'Bob')
form.append('user[friends][]', 'Alice')
form.append('user[friends][]', 'Charlie')
form.append('thumb', new Blob(['hello']), 'thumb.png')

parseFormData(form)
// {
//   a: '1',
//   user: {
//     name: 'John',
//     age: '20',
//     friends: ['Bob', 'Alice', 'Charlie'],
//   },
//   thumb: form.get('thumb'),
// }
```@see{@link https://orpc.dev/docs/helpers/form-data#parseformdata Form Data Helpers - parseFormData}parseFormData } from '@orpc/openapi/helpers'

const const form: FormDataform = new var FormData: new (form?: HTMLFormElement, submitter?: HTMLElement | null) => FormData
The **`FormData`** interface provides a way to construct a set of key/value pairs representing form fields and their values, which can be sent using the fetch(), XMLHttpRequest.send() or navigator.sendBeacon() methods. It uses the same format a form would use if the encoding type were set to "multipart/form-data".

[MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData)FormData()
const form: FormDataform.FormData.append(name: string, value: string | Blob): void (+2 overloads)
The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append)append('name', 'John')
const form: FormDataform.FormData.append(name: string, value: string | Blob): void (+2 overloads)
The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append)append('user[email]', 'john@example.com')
const form: FormDataform.FormData.append(name: string, value: string | Blob): void (+2 overloads)
The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append)append('user[hobbies][]', 'reading')
const form: FormDataform.FormData.append(name: string, value: string | Blob): void (+2 overloads)
The **`append()`** method of the FormData interface appends a new value onto an existing key inside a FormData object, or adds the key if it does not already exist.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append)append('user[hobbies][]', 'gaming')

const const parsed: anyparsed = function parseFormData(form: FormData): any
Parse a form data with [bracket notation](https://orpc.dev/docs/openapi/bracket-notation) syntax
@example```ts
const form = new FormData()
form.append('a', '1')
form.append('user[name]', 'John')
form.append('user[age]', '20')
form.append('user[friends][]', 'Bob')
form.append('user[friends][]', 'Alice')
form.append('user[friends][]', 'Charlie')
form.append('thumb', new Blob(['hello']), 'thumb.png')

parseFormData(form)
// {
//   a: '1',
//   user: {
//     name: 'John',
//     age: '20',
//     friends: ['Bob', 'Alice', 'Charlie'],
//   },
//   thumb: form.get('thumb'),
// }
```@see{@link https://orpc.dev/docs/helpers/form-data#parseformdata Form Data Helpers - parseFormData}parseFormData(const form: FormDataform)
// Result:
// {
//   name: 'John',
//   user: {
//     email: 'john@example.com',
//     hobbies: ['reading', 'gaming']
//   }
// }

getIssueMessage

Extracts validation error messages from standard schema issues using bracket notation paths.

import { function getIssueMessage(error: unknown, path: string): string | undefined
Gets the issue message from the error for a given field path.
@remarks**Note**: Requires validation errors to follow the standard schema issue format, stored under `data.issues` — customized validation errors may not be found.@example```tsx
const { error, data, execute } = useServerAction(someAction)

return <form action={(form) => execute(parseFormData(form))}>
  <input name="user[name]" type="text" />
  <p>{getIssueMessage(error, 'user[name]')}</p>

  <input name="user[age]" type="number" />
  <p>{getIssueMessage(error, 'user[age]')}</p>

  <input name="images[]" type="file" />
  <p>{getIssueMessage(error, 'images[]')}</p>
</form>
```@paramerror - The error (can be anything) can contain `data.issues` (standard schema issues)@parampath - The path of the field that has the issue follow [bracket notation](https://orpc.dev/docs/openapi/bracket-notation)@see{@link https://orpc.dev/docs/helpers/form-data#getissuemessage Form Data Helpers - getIssueMessage}getIssueMessage } from '@orpc/openapi/helpers'

const 
const error: {
    data: {
        issues: {
            path: string[];
            message: string;
        }[];
    };
}error = {
  
data: {
    issues: {
        path: string[];
        message: string;
    }[];
}data: {
    
issues: {
    path: string[];
    message: string;
}[]issues: [
      {
        path: string[]path: ['user', 'email'],
        message: stringmessage: 'Invalid email format'
      }
    ]
  }
}

const const emailError: string | undefinedemailError = function getIssueMessage(error: unknown, path: string): string | undefined
Gets the issue message from the error for a given field path.
@remarks**Note**: Requires validation errors to follow the standard schema issue format, stored under `data.issues` — customized validation errors may not be found.@example```tsx
const { error, data, execute } = useServerAction(someAction)

return <form action={(form) => execute(parseFormData(form))}>
  <input name="user[name]" type="text" />
  <p>{getIssueMessage(error, 'user[name]')}</p>

  <input name="user[age]" type="number" />
  <p>{getIssueMessage(error, 'user[age]')}</p>

  <input name="images[]" type="file" />
  <p>{getIssueMessage(error, 'images[]')}</p>
</form>
```@paramerror - The error (can be anything) can contain `data.issues` (standard schema issues)@parampath - The path of the field that has the issue follow [bracket notation](https://orpc.dev/docs/openapi/bracket-notation)@see{@link https://orpc.dev/docs/helpers/form-data#getissuemessage Form Data Helpers - getIssueMessage}getIssueMessage(
const error: {
    data: {
        issues: {
            path: string[];
            message: string;
        }[];
    };
}error, 'user[email]')
// Returns: 'Invalid email format'

const const tagError: string | undefinedtagError = function getIssueMessage(error: unknown, path: string): string | undefined
Gets the issue message from the error for a given field path.
@remarks**Note**: Requires validation errors to follow the standard schema issue format, stored under `data.issues` — customized validation errors may not be found.@example```tsx
const { error, data, execute } = useServerAction(someAction)

return <form action={(form) => execute(parseFormData(form))}>
  <input name="user[name]" type="text" />
  <p>{getIssueMessage(error, 'user[name]')}</p>

  <input name="user[age]" type="number" />
  <p>{getIssueMessage(error, 'user[age]')}</p>

  <input name="images[]" type="file" />
  <p>{getIssueMessage(error, 'images[]')}</p>
</form>
```@paramerror - The error (can be anything) can contain `data.issues` (standard schema issues)@parampath - The path of the field that has the issue follow [bracket notation](https://orpc.dev/docs/openapi/bracket-notation)@see{@link https://orpc.dev/docs/helpers/form-data#getissuemessage Form Data Helpers - getIssueMessage}getIssueMessage(
const error: {
    data: {
        issues: {
            path: string[];
            message: string;
        }[];
    };
}error, 'user[tags][]')
// Returns error message for any array item

const const anyError: string | undefinedanyError = function getIssueMessage(error: unknown, path: string): string | undefined
Gets the issue message from the error for a given field path.
@remarks**Note**: Requires validation errors to follow the standard schema issue format, stored under `data.issues` — customized validation errors may not be found.@example```tsx
const { error, data, execute } = useServerAction(someAction)

return <form action={(form) => execute(parseFormData(form))}>
  <input name="user[name]" type="text" />
  <p>{getIssueMessage(error, 'user[name]')}</p>

  <input name="user[age]" type="number" />
  <p>{getIssueMessage(error, 'user[age]')}</p>

  <input name="images[]" type="file" />
  <p>{getIssueMessage(error, 'images[]')}</p>
</form>
```@paramerror - The error (can be anything) can contain `data.issues` (standard schema issues)@parampath - The path of the field that has the issue follow [bracket notation](https://orpc.dev/docs/openapi/bracket-notation)@see{@link https://orpc.dev/docs/helpers/form-data#getissuemessage Form Data Helpers - getIssueMessage}getIssueMessage('anything', 'path')
// Returns undefined if cannot find issue

Usage Example

import { getIssueMessage, parseFormData } from '@orpc/openapi/helpers'

export function ContactForm() {
  const [error, setError] = useState()

  const handleSubmit = (form: FormData) => {
    try {
      const data = parseFormData(form)
      // Process structured data
    }
    catch (error) {
      setError(error)
    }
  }

  return (
    <form action={handleSubmit}>
      <input name="user[name]" type="text" />
      <span>{getIssueMessage(error, 'user[name]')}</span>

      <input name="user[emails][]" type="email" />
      <span>{getIssueMessage(error, 'user[emails][]')}</span>

      <button type="submit">Submit</button>
    </form>
  )
}