From 409451a4473efab471d725a93fd8dbb233e588f0 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:25:10 +0200 Subject: [PATCH 1/9] Clarify standalone startTransition error handling --- src/content/reference/react/startTransition.md | 4 +++- src/content/reference/react/useTransition.md | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index fba28f6d1bc..219ce4f8ee2 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -51,6 +51,8 @@ function TabContainer() { * `startTransition` does not provide a way to track whether a Transition is pending. To show a pending indicator while the Transition is ongoing, you need [`useTransition`](/reference/react/useTransition) instead. +* The standalone `startTransition` function is not associated with a component. If the `action` throws an error or returns a rejected Promise, React reports the error as uncaught instead of sending it to an Error Boundary. To send errors to the nearest Error Boundary, use the `startTransition` function returned by [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-an-error-boundary). + * You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook return value, try [`useDeferredValue`](/reference/react/useDeferredValue) instead. * The function you pass to `startTransition` is called immediately, marking all state updates that happen while it executes as Transitions. If you try to perform state updates in a `setTimeout`, for example, they won't be marked as Transitions. @@ -92,7 +94,7 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex -`startTransition` is very similar to [`useTransition`](/reference/react/useTransition), except that it does not provide the `isPending` flag to track whether a Transition is ongoing. You can call `startTransition` when `useTransition` is not available. For example, `startTransition` works outside components, such as from a data library. +Unlike the `startTransition` function returned by [`useTransition`](/reference/react/useTransition), the standalone `startTransition` does not provide the `isPending` flag and is not associated with a component. This means React cannot identify which Error Boundary should handle errors thrown by the `action`, so it reports them as uncaught. You can call the standalone `startTransition` when `useTransition` is not available, such as from a data library outside a component. [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) diff --git a/src/content/reference/react/useTransition.md b/src/content/reference/react/useTransition.md index 472224e58d9..84ec2abed3d 100644 --- a/src/content/reference/react/useTransition.md +++ b/src/content/reference/react/useTransition.md @@ -1567,7 +1567,7 @@ main { ### Displaying an error to users with an error boundary {/*displaying-an-error-to-users-with-error-boundary*/} -If a function passed to `startTransition` throws an error, you can display an error to your user with an [error boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary). To use an error boundary, wrap the component where you are calling the `useTransition` in an error boundary. Once the function passed to `startTransition` errors, the fallback for the error boundary will be displayed. +The `startTransition` function returned by `useTransition` is associated with the component that called the Hook. If a function passed to it throws an error, React sends the error to the nearest [error boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary). Wrap the component that calls `useTransition` in an error boundary to display a fallback when an Action throws. @@ -1738,7 +1738,7 @@ This is a JavaScript limitation due to React losing the scope of the async conte ### I want to call `useTransition` from outside a component {/*i-want-to-call-usetransition-from-outside-a-component*/} -You can't call `useTransition` outside a component because it's a Hook. In this case, use the standalone [`startTransition`](/reference/react/startTransition) method instead. It works the same way, but it doesn't provide the `isPending` indicator. +You can't call `useTransition` outside a component because it's a Hook. In this case, use the standalone [`startTransition`](/reference/react/startTransition) function instead. It can mark state updates as Transitions, but it is not associated with a component. This means it cannot provide an `isPending` indicator or send errors to the nearest Error Boundary. --- From fe295e652b0cb73c834ce6761dd534beba91c482 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:34:33 +0200 Subject: [PATCH 2/9] Polish startTransition error handling docs --- src/content/reference/react/startTransition.md | 13 +++++++++++-- src/content/reference/react/useTransition.md | 13 +++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index 219ce4f8ee2..676bbd41454 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -51,7 +51,12 @@ function TabContainer() { * `startTransition` does not provide a way to track whether a Transition is pending. To show a pending indicator while the Transition is ongoing, you need [`useTransition`](/reference/react/useTransition) instead. -* The standalone `startTransition` function is not associated with a component. If the `action` throws an error or returns a rejected Promise, React reports the error as uncaught instead of sending it to an Error Boundary. To send errors to the nearest Error Boundary, use the `startTransition` function returned by [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-an-error-boundary). +* The standalone `startTransition` function is not associated with a component. + If the `action` throws an error or returns a rejected Promise, React reports + the error as uncaught, and an Error Boundary does not handle it. To let the + nearest Error Boundary handle these errors, use the `startTransition` + function returned by + [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary). * You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook return value, try [`useDeferredValue`](/reference/react/useDeferredValue) instead. @@ -94,7 +99,11 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex -Unlike the `startTransition` function returned by [`useTransition`](/reference/react/useTransition), the standalone `startTransition` does not provide the `isPending` flag and is not associated with a component. This means React cannot identify which Error Boundary should handle errors thrown by the `action`, so it reports them as uncaught. You can call the standalone `startTransition` when `useTransition` is not available, such as from a data library outside a component. +`startTransition` does not provide the `isPending` flag. Call it from code that +cannot call Hooks, such as data-library code outside a component. Unlike the +function returned by [`useTransition`](/reference/react/useTransition), the +standalone `startTransition` is not associated with a component. As a result, +an Error Boundary cannot handle errors from its Action. [See Caveats.](#caveats) [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) diff --git a/src/content/reference/react/useTransition.md b/src/content/reference/react/useTransition.md index 84ec2abed3d..d37cc4f3abd 100644 --- a/src/content/reference/react/useTransition.md +++ b/src/content/reference/react/useTransition.md @@ -1567,7 +1567,12 @@ main { ### Displaying an error to users with an error boundary {/*displaying-an-error-to-users-with-error-boundary*/} -The `startTransition` function returned by `useTransition` is associated with the component that called the Hook. If a function passed to it throws an error, React sends the error to the nearest [error boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary). Wrap the component that calls `useTransition` in an error boundary to display a fallback when an Action throws. +The `startTransition` function returned by `useTransition` is associated with +the component that called the Hook. If the Action passed to `startTransition` +throws an error or returns a rejected Promise, the nearest +[Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary) +can handle the error. Wrap the component that calls `useTransition` in an Error +Boundary to display a fallback for these errors. @@ -1738,7 +1743,11 @@ This is a JavaScript limitation due to React losing the scope of the async conte ### I want to call `useTransition` from outside a component {/*i-want-to-call-usetransition-from-outside-a-component*/} -You can't call `useTransition` outside a component because it's a Hook. In this case, use the standalone [`startTransition`](/reference/react/startTransition) function instead. It can mark state updates as Transitions, but it is not associated with a component. This means it cannot provide an `isPending` indicator or send errors to the nearest Error Boundary. +You can't call `useTransition` outside a component because it's a Hook. In this +case, use the standalone [`startTransition`](/reference/react/startTransition) +function instead. It marks state updates as Transitions but does not provide the +`isPending` flag. Because the standalone function is not associated with a +component, an Error Boundary cannot handle errors from its Action. --- From e14466595e616a9326248c84dae6f867dcc1fb54 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:48:07 +0200 Subject: [PATCH 3/9] Describe startTransition differences neutrally --- .../reference/react/startTransition.md | 20 ++++++++++--------- src/content/reference/react/useTransition.md | 4 ++-- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index 676bbd41454..164fd3eb9ab 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -53,10 +53,11 @@ function TabContainer() { * The standalone `startTransition` function is not associated with a component. If the `action` throws an error or returns a rejected Promise, React reports - the error as uncaught, and an Error Boundary does not handle it. To let the - nearest Error Boundary handle these errors, use the `startTransition` - function returned by - [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary). + the error as uncaught, and an Error Boundary does not handle it. In contrast, + the `startTransition` function returned by + [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary) + is associated with a component, so the nearest Error Boundary can handle + these errors. * You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook return value, try [`useDeferredValue`](/reference/react/useDeferredValue) instead. @@ -99,11 +100,12 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex -`startTransition` does not provide the `isPending` flag. Call it from code that -cannot call Hooks, such as data-library code outside a component. Unlike the -function returned by [`useTransition`](/reference/react/useTransition), the -standalone `startTransition` is not associated with a component. As a result, -an Error Boundary cannot handle errors from its Action. [See Caveats.](#caveats) +The standalone `startTransition` and the function returned by +[`useTransition`](/reference/react/useTransition) both mark state updates as +Transitions. The standalone function does not provide the `isPending` flag and +is not associated with a component, so an Error Boundary cannot handle errors +from its Action. Unlike `useTransition`, the standalone `startTransition` is not +a Hook and can be called outside components. [See Caveats.](#caveats) [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) diff --git a/src/content/reference/react/useTransition.md b/src/content/reference/react/useTransition.md index d37cc4f3abd..3fe07179cca 100644 --- a/src/content/reference/react/useTransition.md +++ b/src/content/reference/react/useTransition.md @@ -1744,8 +1744,8 @@ This is a JavaScript limitation due to React losing the scope of the async conte ### I want to call `useTransition` from outside a component {/*i-want-to-call-usetransition-from-outside-a-component*/} You can't call `useTransition` outside a component because it's a Hook. In this -case, use the standalone [`startTransition`](/reference/react/startTransition) -function instead. It marks state updates as Transitions but does not provide the +case, the standalone [`startTransition`](/reference/react/startTransition) +function can mark state updates as Transitions. It does not provide the `isPending` flag. Because the standalone function is not associated with a component, an Error Boundary cannot handle errors from its Action. From f54d0cd71eb8563139233e2d1bea665adf84e315 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:51:51 +0200 Subject: [PATCH 4/9] Clarify startTransition callback wording --- .../reference/react/startTransition.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index 164fd3eb9ab..a3a2bae07c6 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -51,17 +51,17 @@ function TabContainer() { * `startTransition` does not provide a way to track whether a Transition is pending. To show a pending indicator while the Transition is ongoing, you need [`useTransition`](/reference/react/useTransition) instead. -* The standalone `startTransition` function is not associated with a component. - If the `action` throws an error or returns a rejected Promise, React reports - the error as uncaught, and an Error Boundary does not handle it. In contrast, - the `startTransition` function returned by - [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary) - is associated with a component, so the nearest Error Boundary can handle - these errors. - * You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook return value, try [`useDeferredValue`](/reference/react/useDeferredValue) instead. -* The function you pass to `startTransition` is called immediately, marking all state updates that happen while it executes as Transitions. If you try to perform state updates in a `setTimeout`, for example, they won't be marked as Transitions. +* The function you pass to `startTransition` is called immediately, marking all + state updates that happen while it executes as Transitions. If you try to + perform state updates in a `setTimeout`, for example, they won't be marked as + Transitions. If the function throws an error or returns a rejected Promise, + React reports the error as uncaught. Unlike the `startTransition` function + returned by + [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary), + the standalone `startTransition` function is not associated with a component, + so an Error Boundary does not handle these errors. * You must wrap any state updates after any async requests in another `startTransition` to mark them as Transitions. This is a known limitation that we will fix in the future (see [Troubleshooting](/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition)). @@ -103,9 +103,11 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex The standalone `startTransition` and the function returned by [`useTransition`](/reference/react/useTransition) both mark state updates as Transitions. The standalone function does not provide the `isPending` flag and -is not associated with a component, so an Error Boundary cannot handle errors -from its Action. Unlike `useTransition`, the standalone `startTransition` is not -a Hook and can be called outside components. [See Caveats.](#caveats) +is not associated with a component. If the function passed to it throws an +error or returns a rejected Promise, React reports the error as uncaught instead +of allowing an Error Boundary to handle it. Unlike `useTransition`, the +standalone `startTransition` is not a Hook and can be called outside components. +[See Caveats.](#caveats) [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) From 790edb832f8b598f8d5df82bb029340d3f52d0ae Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:55:38 +0200 Subject: [PATCH 5/9] Remove repeated startTransition caveat --- src/content/reference/react/startTransition.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index a3a2bae07c6..b088309aedd 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -57,11 +57,10 @@ function TabContainer() { state updates that happen while it executes as Transitions. If you try to perform state updates in a `setTimeout`, for example, they won't be marked as Transitions. If the function throws an error or returns a rejected Promise, - React reports the error as uncaught. Unlike the `startTransition` function - returned by - [`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary), - the standalone `startTransition` function is not associated with a component, - so an Error Boundary does not handle these errors. + React reports the error as uncaught because the standalone `startTransition` + function is not associated with a component. [Learn how to display errors + from `useTransition` with an Error + Boundary.](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary) * You must wrap any state updates after any async requests in another `startTransition` to mark them as Transitions. This is a known limitation that we will fix in the future (see [Troubleshooting](/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition)). @@ -102,11 +101,8 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex The standalone `startTransition` and the function returned by [`useTransition`](/reference/react/useTransition) both mark state updates as -Transitions. The standalone function does not provide the `isPending` flag and -is not associated with a component. If the function passed to it throws an -error or returns a rejected Promise, React reports the error as uncaught instead -of allowing an Error Boundary to handle it. Unlike `useTransition`, the -standalone `startTransition` is not a Hook and can be called outside components. +Transitions. Unlike `useTransition`, the standalone function does not provide +the `isPending` flag. It is not a Hook, so you can call it outside components. [See Caveats.](#caveats) [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) From 73e0b39a46e5b708013ffd319daeb6687c207cb5 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 15:59:02 +0200 Subject: [PATCH 6/9] Preserve existing startTransition guidance --- .../reference/react/startTransition.md | 22 ++++++++----------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index b088309aedd..19213c6532c 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -53,14 +53,7 @@ function TabContainer() { * You can wrap an update into a Transition only if you have access to the `set` function of that state. If you want to start a Transition in response to some prop or a custom Hook return value, try [`useDeferredValue`](/reference/react/useDeferredValue) instead. -* The function you pass to `startTransition` is called immediately, marking all - state updates that happen while it executes as Transitions. If you try to - perform state updates in a `setTimeout`, for example, they won't be marked as - Transitions. If the function throws an error or returns a rejected Promise, - React reports the error as uncaught because the standalone `startTransition` - function is not associated with a component. [Learn how to display errors - from `useTransition` with an Error - Boundary.](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary) +* The function you pass to `startTransition` is called immediately, marking all state updates that happen while it executes as Transitions. If you try to perform state updates in a `setTimeout`, for example, they won't be marked as Transitions. * You must wrap any state updates after any async requests in another `startTransition` to mark them as Transitions. This is a known limitation that we will fix in the future (see [Troubleshooting](/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition)). @@ -99,11 +92,14 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex -The standalone `startTransition` and the function returned by -[`useTransition`](/reference/react/useTransition) both mark state updates as -Transitions. Unlike `useTransition`, the standalone function does not provide -the `isPending` flag. It is not a Hook, so you can call it outside components. -[See Caveats.](#caveats) +`startTransition` is very similar to +[`useTransition`](/reference/react/useTransition), except that it does not +provide the `isPending` flag to track whether a Transition is ongoing. The +standalone function is also not associated with a component, so if the function +passed to it throws an error or returns a rejected Promise, React reports the +error as uncaught. You can call `startTransition` when `useTransition` is not +available. For example, `startTransition` works outside components, such as from +a data library. [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition) From 3b81a6f1e876cf97803ce38c6d39f9d68cee3567 Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Wed, 9 Sep 2026 16:04:01 +0200 Subject: [PATCH 7/9] Preserve useTransition error guidance --- src/content/reference/react/useTransition.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/src/content/reference/react/useTransition.md b/src/content/reference/react/useTransition.md index 3fe07179cca..76f105cd598 100644 --- a/src/content/reference/react/useTransition.md +++ b/src/content/reference/react/useTransition.md @@ -1567,12 +1567,7 @@ main { ### Displaying an error to users with an error boundary {/*displaying-an-error-to-users-with-error-boundary*/} -The `startTransition` function returned by `useTransition` is associated with -the component that called the Hook. If the Action passed to `startTransition` -throws an error or returns a rejected Promise, the nearest -[Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary) -can handle the error. Wrap the component that calls `useTransition` in an Error -Boundary to display a fallback for these errors. +If a function passed to `startTransition` throws an error or returns a rejected Promise, you can display an error to your user with an [error boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary). To use an error boundary, wrap the component where you are calling the `useTransition` in an error boundary. Once the function passed to `startTransition` errors, the fallback for the error boundary will be displayed. From e308481e78d41eb5c13bb41edc4dea7155d49a76 Mon Sep 17 00:00:00 2001 From: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com> Date: Thu, 10 Sep 2026 11:27:14 +0200 Subject: [PATCH 8/9] Update src/content/reference/react/useTransition.md Co-authored-by: Sebastian "Sebbie" Silbermann --- src/content/reference/react/useTransition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/reference/react/useTransition.md b/src/content/reference/react/useTransition.md index 76f105cd598..6533a201bf3 100644 --- a/src/content/reference/react/useTransition.md +++ b/src/content/reference/react/useTransition.md @@ -1742,7 +1742,7 @@ You can't call `useTransition` outside a component because it's a Hook. In this case, the standalone [`startTransition`](/reference/react/startTransition) function can mark state updates as Transitions. It does not provide the `isPending` flag. Because the standalone function is not associated with a -component, an Error Boundary cannot handle errors from its Action. +component, an Error Boundary cannot handle errors from its Transition. --- From e1b8866944ec8cdb968b3d6daac84f2f408501bb Mon Sep 17 00:00:00 2001 From: Aurora Scharff Date: Thu, 10 Sep 2026 11:47:00 +0200 Subject: [PATCH 9/9] Clarify standalone startTransition error reporting --- src/content/reference/react/startTransition.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/src/content/reference/react/startTransition.md b/src/content/reference/react/startTransition.md index 19213c6532c..1da920d5e92 100644 --- a/src/content/reference/react/startTransition.md +++ b/src/content/reference/react/startTransition.md @@ -92,14 +92,7 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex -`startTransition` is very similar to -[`useTransition`](/reference/react/useTransition), except that it does not -provide the `isPending` flag to track whether a Transition is ongoing. The -standalone function is also not associated with a component, so if the function -passed to it throws an error or returns a rejected Promise, React reports the -error as uncaught. You can call `startTransition` when `useTransition` is not -available. For example, `startTransition` works outside components, such as from -a data library. +`startTransition` is very similar to [`useTransition`](/reference/react/useTransition), except that it does not provide the `isPending` flag to track whether a Transition is ongoing. The standalone function is also not associated with a component, so if the function passed to it throws an error or returns a rejected Promise, React reports the error with [`reportError`](https://developer.mozilla.org/en-US/docs/Web/API/Window/reportError). You can call `startTransition` when `useTransition` is not available. For example, `startTransition` works outside components, such as from a data library. [Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition)