diff --git a/docs/framework/angular/guides/submission-handling.md b/docs/framework/angular/guides/submission-handling.md index 4f503f0cd..e6cb6069a 100644 --- a/docs/framework/angular/guides/submission-handling.md +++ b/docs/framework/angular/guides/submission-handling.md @@ -3,6 +3,97 @@ id: submission-handling title: Submission handling --- +## Error handling + +When a user submits a form, there are several ways errors can occur — each requiring its own handling approach. TanStack Form gives you the flexibility to handle errors your way. To help you get started, here’s how to approach the three most common types of errors you’ll run into: + +- **Synchronous user errors** – Issues you can catch right away, like a field being left empty or text that's too short. +- **Asynchronous user errors** – Issues that come up after submission, like finding out a username is already taken. +- **Server errors** – Unexpected problems on the backend, such as a failed request or an unknown error. + +> [!TIP] +> If you need help understanding how validation works in TanStack Form, be sure to check out the [form validation](../validation.md) guide! + +### Synchronous user errors + +These are validation issues that can be detected immediately on the client side, even before the form is submitted. They are typically managed using both form-level and field-level validators, as shown in the example below: + +```angular-ts +@Component({ + imports: [TanStackField], + template: ` + + + + `, +}) +export class AppComponent { + ageValidator: FieldValidateFn = ({ value }) => + value < 13 ? 'You must be 13 to make an account' : undefined + + // ... +} +``` + +### Asynchronous user errors + +Asynchronous errors usually occur after the form is submitted, often due to external checks — like verifying whether a username or email is already taken. These kinds of errors can be handled using the async variants of form and field validators. + +Since these requests are usually at form level, see how you can [set field-level errors from the form's validators](../validation.md). + +```angular-ts +form = injectForm({ + // ... + validators: { + onSubmitAsync: async ({ value }) => { + // Validate the value on the server + const response = await createAccount(value) + + if (response.isError) { + // Username is taken, return an error + return 'Username is already taken!' + } + + // The account creation was a success. There is no error that needs to be shown. + return null + }, + }, +}) +``` + +### Server errors + +Server errors are unexpected failures that happen during submission — like connectivity issues or internal server faults. These aren't related to user input and therefore **should not be part of form validation**. + +These kinds of errors are typically handled by an external library, such as `TanStack Query`: + +```angular-ts +// Using TanStack Query for data mutations +createAccountMutation = injectMutation(() => ({ +// ... +})) + +form = injectForm({ + // ... + onSubmit: async ({ value }) => { + // If an error happens, they are accessible through + // `createAccountMutation.error` + createAccountMutation.mutate(value, { + onSuccess: () => { + // handle success by navigate to another route e.g. + }, + }) + }, +}) +``` + ## Passing additional data to submission handling You may have multiple types of submission behaviour, for example, going back to another page or staying on the form. diff --git a/docs/framework/react/guides/submission-handling.md b/docs/framework/react/guides/submission-handling.md index 65b9c197d..dc549f2ec 100644 --- a/docs/framework/react/guides/submission-handling.md +++ b/docs/framework/react/guides/submission-handling.md @@ -3,6 +3,79 @@ id: submission-handling title: Submission handling --- +## Error handling + +When a user submits a form, there are several ways errors can occur — each requiring its own handling approach. TanStack Form gives you the flexibility to handle errors your way. To help you get started, here’s how to approach the three most common types of errors you’ll run into: + +- **Synchronous user errors** – Issues you can catch right away, like a field being left empty or text that's too short. +- **Asynchronous user errors** – Issues that come up after submission, like finding out a username is already taken. +- **Server errors** – Unexpected problems on the backend, such as a failed request or an unknown error. + +> [!TIP] +> If you need help understanding how validation works in TanStack Form, be sure to check out the [form validation](../validation.md) guide! + +### Synchronous user errors + +These are validation issues that can be detected immediately on the client side, even before the form is submitted. They are typically managed using both form-level and field-level validators, as shown in the example below: + +```tsx + + value < 13 ? 'You must be 13 to make an account' : undefined, + }} + children={{() => <>{/* ... */}}} +/> +``` + +### Asynchronous user errors + +Asynchronous errors usually occur after the form is submitted, often due to external checks — like verifying whether a username or email is already taken. These kinds of errors can be handled using the async variants of form and field validators. + +Since these requests are usually at form level, see how you can [set field-level errors from the form's validators](../validation.md). + +```tsx +const form = useForm({ + // ... + validators: { + onSubmitAsync: async ({ value }) => { + // Validate the value on the server + const response = await createAccount(value) + + if (response.isError) { + // Username is taken, return an error for the username field + return 'Username is already taken!' + } + // The account creation was a success. There is no error that needs to be shown. + return null + }, + }, +}) +``` + +### Server errors + +Server errors are unexpected failures that happen during submission — like connectivity issues or internal server faults. These aren't related to user input and therefore **should not be part of form validation**. + +These kinds of errors are typically handled by an external library, such as `TanStack Query`: + +```tsx +// Using TanStack Query for data mutations +const createAccountMutation = useMutation({ + /* ... */ +}) + +const form = useForm({ + // ... + onSubmit: async ({ value }) => { + // If an error happens, they are accessible through + // `createAccountMutation.error` + await createAccountMutation.mutateAsync(value) + }, +}) +``` + ## Passing additional data to submission handling You may have multiple types of submission behaviour, for example, going back to another page or staying on the form. diff --git a/docs/framework/solid/guides/submission-handling.md b/docs/framework/solid/guides/submission-handling.md index 1cbc8b251..8c920b942 100644 --- a/docs/framework/solid/guides/submission-handling.md +++ b/docs/framework/solid/guides/submission-handling.md @@ -3,6 +3,79 @@ id: submission-handling title: Submission handling --- +## Error handling + +When a user submits a form, there are several ways errors can occur — each requiring its own handling approach. TanStack Form gives you the flexibility to handle errors your way. To help you get started, here’s how to approach the three most common types of errors you’ll run into: + +- **Synchronous user errors** – Issues you can catch right away, like a field being left empty or text that's too short. +- **Asynchronous user errors** – Issues that come up after submission, like finding out a username is already taken. +- **Server errors** – Unexpected problems on the backend, such as a failed request or an unknown error. + +> [!TIP] +> If you need help understanding how validation works in TanStack Form, be sure to check out the [form validation](../validation.md) guide! + +### Synchronous user errors + +These are validation issues that can be detected immediately on the client side, even before the form is submitted. They are typically managed using both form-level and field-level validators, as shown in the example below: + +```tsx + + value < 13 ? 'You must be 13 to make an account' : undefined, + }} +> + {() => <>{/* ... */}} + +``` + +### Asynchronous user errors + +Asynchronous errors usually occur after the form is submitted, often due to external checks — like verifying whether a username or email is already taken. These kinds of errors can be handled using the async variants of form and field validators. + +Since these requests are usually at form level, see how you can [set field-level errors from the form's validators](../validation.md). + +```tsx +const form = createForm(() => ({ + // ... + validators: { + onSubmitAsync: async ({ value }) => { + // Validate the value on the server + const response = await createAccount(value) + if (response.isError) { + // Username is taken, return an error for the username field + return 'Account is already taken!' + } + // The account creation was a success. There is no error that needs to be shown. + return null + }, + }, +})) +``` + +### Server errors + +Server errors are unexpected failures that happen during submission — like connectivity issues or internal server faults. These aren't related to user input and therefore **should not be part of form validation**. + +These kinds of errors are typically handled by an external library, such as `TanStack Query`: + +```tsx +// Using TanStack Query for data mutations +const createAccountMutation = useMutation(() => ({ + /* ... */ +})) + +const form = createForm(() => ({ + // ... + onSubmit: async ({ value }) => { + // If an error happens, they are accessible through + // `createAccountMutation.error` + await createAccountMutation.mutateAsync(value) + }, +})) +``` + ## Passing additional data to submission handling You may have multiple types of submission behaviour, for example, going back to another page or staying on the form. diff --git a/docs/framework/vue/guides/submission-handling.md b/docs/framework/vue/guides/submission-handling.md index 6ed8e9819..475085980 100644 --- a/docs/framework/vue/guides/submission-handling.md +++ b/docs/framework/vue/guides/submission-handling.md @@ -3,6 +3,95 @@ id: submission-handling title: Submission handling --- +## Error handling + +When a user submits a form, there are several ways errors can occur — each requiring its own handling approach. TanStack Form gives you the flexibility to handle errors your way. To help you get started, here’s how to approach the three most common types of errors you’ll run into: + +- **Synchronous user errors** – Issues you can catch right away, like a field being left empty or text that's too short. +- **Asynchronous user errors** – Issues that come up after submission, like finding out a username is already taken. +- **Server errors** – Unexpected problems on the backend, such as a failed request or an unknown error. + +> [!TIP] +> If you need help understanding how validation works in TanStack Form, be sure to check out the [form validation](../validation.md) guide! + +### Synchronous user errors + +These are validation issues that can be detected immediately on the client side, even before the form is submitted. They are typically managed using both form-level and field-level validators, as shown in the example below: + +```vue + +``` + +### Asynchronous user errors + +Asynchronous errors usually occur after the form is submitted, often due to external checks — like verifying whether a username or email is already taken. These kinds of errors can be handled using the async variants of form and field validators. + +Since these requests are usually at form level, see how you can [set field-level errors from the form's validators](../validation.md). + +```vue + +``` + +### Server errors + +Server errors are unexpected failures that happen during submission — like connectivity issues or internal server faults. These aren't related to user input and therefore **should not be part of form validation**. + +These kinds of errors are typically handled by an external library, such as `TanStack Query`: + +```vue + +``` + ## Passing additional data to submission handling You may have multiple types of submission behaviour, for example, going back to another page or staying on the form.