From f186229993ca7d10b8a711ecfb0bee941fdfa2e3 Mon Sep 17 00:00:00 2001 From: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com> Date: Sun, 8 Jun 2025 20:23:34 +0200 Subject: [PATCH 1/6] docs: expand submission handling in react --- .../react/guides/submission-handling.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/docs/framework/react/guides/submission-handling.md b/docs/framework/react/guides/submission-handling.md index 65b9c197d..33fc617b0 100644 --- a/docs/framework/react/guides/submission-handling.md +++ b/docs/framework/react/guides/submission-handling.md @@ -3,6 +3,84 @@ 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** – Things 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 { + fields: { + username: response.message, + }, + } + } + // 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: ({ value }) => { + // If an error happens, they are accessible through + // `createAccountMutation.error` + return 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. From 19196cd0f911e18ff7d2d8daef494ed4bae9db31 Mon Sep 17 00:00:00 2001 From: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com> Date: Sun, 8 Jun 2025 20:35:25 +0200 Subject: [PATCH 2/6] docs: expand submission handling in solid --- .../react/guides/submission-handling.md | 4 +- .../solid/guides/submission-handling.md | 77 +++++++++++++++++++ 2 files changed, 79 insertions(+), 2 deletions(-) diff --git a/docs/framework/react/guides/submission-handling.md b/docs/framework/react/guides/submission-handling.md index 33fc617b0..f3f9df417 100644 --- a/docs/framework/react/guides/submission-handling.md +++ b/docs/framework/react/guides/submission-handling.md @@ -73,10 +73,10 @@ const createAccountMutation = useMutation({ const form = useForm({ // ... - onSubmit: ({ value }) => { + onSubmit: async ({ value }) => { // If an error happens, they are accessible through // `createAccountMutation.error` - return createAccountMutation.mutateAsync(value) + await createAccountMutation.mutateAsync(value) }, }) ``` diff --git a/docs/framework/solid/guides/submission-handling.md b/docs/framework/solid/guides/submission-handling.md index 1cbc8b251..6b1fcd7f3 100644 --- a/docs/framework/solid/guides/submission-handling.md +++ b/docs/framework/solid/guides/submission-handling.md @@ -3,6 +3,83 @@ 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** – Things 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 { + fields: { + username: response.message, + }, + } + } + // 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. From 3b47efe592f9a59592c8c1eb1f78dc1cf7f7aae2 Mon Sep 17 00:00:00 2001 From: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com> Date: Sun, 8 Jun 2025 20:40:38 +0200 Subject: [PATCH 3/6] docs: expand submission handling in vue --- .../react/guides/submission-handling.md | 1 - .../vue/guides/submission-handling.md | 93 +++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) diff --git a/docs/framework/react/guides/submission-handling.md b/docs/framework/react/guides/submission-handling.md index f3f9df417..7ab60f46d 100644 --- a/docs/framework/react/guides/submission-handling.md +++ b/docs/framework/react/guides/submission-handling.md @@ -22,7 +22,6 @@ These are validation issues that can be detected immediately on the client side, value < 13 ? 'You must be 13 to make an account' : undefined, }} diff --git a/docs/framework/vue/guides/submission-handling.md b/docs/framework/vue/guides/submission-handling.md index 6ed8e9819..164fa97fa 100644 --- a/docs/framework/vue/guides/submission-handling.md +++ b/docs/framework/vue/guides/submission-handling.md @@ -3,6 +3,99 @@ 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** – Things 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. From 835d6c610f33d768b954ca30af17c3a51ddf4bf6 Mon Sep 17 00:00:00 2001 From: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com> Date: Sun, 8 Jun 2025 21:02:37 +0200 Subject: [PATCH 4/6] docs: fix validation hyperlink --- docs/framework/react/guides/submission-handling.md | 4 ++-- docs/framework/solid/guides/submission-handling.md | 4 ++-- docs/framework/vue/guides/submission-handling.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/framework/react/guides/submission-handling.md b/docs/framework/react/guides/submission-handling.md index 7ab60f46d..2efe33e7c 100644 --- a/docs/framework/react/guides/submission-handling.md +++ b/docs/framework/react/guides/submission-handling.md @@ -12,7 +12,7 @@ When a user submits a form, there are several ways errors can occur — each req - **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! +> 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 @@ -33,7 +33,7 @@ These are validation issues that can be detected immediately on the client side, 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). +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({ diff --git a/docs/framework/solid/guides/submission-handling.md b/docs/framework/solid/guides/submission-handling.md index 6b1fcd7f3..a7b5e1614 100644 --- a/docs/framework/solid/guides/submission-handling.md +++ b/docs/framework/solid/guides/submission-handling.md @@ -12,7 +12,7 @@ When a user submits a form, there are several ways errors can occur — each req - **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! +> 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 @@ -34,7 +34,7 @@ These are validation issues that can be detected immediately on the client side, 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). +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(() => ({ diff --git a/docs/framework/vue/guides/submission-handling.md b/docs/framework/vue/guides/submission-handling.md index 164fa97fa..fec47b26a 100644 --- a/docs/framework/vue/guides/submission-handling.md +++ b/docs/framework/vue/guides/submission-handling.md @@ -12,7 +12,7 @@ When a user submits a form, there are several ways errors can occur — each req - **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! +> 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 @@ -40,7 +40,7 @@ These are validation issues that can be detected immediately on the client side, 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). +Since these requests are usually at form level, see how you can [set field-level errors from the form's validators](../validation.md). ```vue