Skip to content

Commit fe295e6

Browse files
committed
Polish startTransition error handling docs
1 parent 409451a commit fe295e6

2 files changed

Lines changed: 22 additions & 4 deletions

File tree

‎src/content/reference/react/startTransition.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,12 @@ function TabContainer() {
5151

5252
* `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.
5353

54-
* 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).
54+
* The standalone `startTransition` function is not associated with a component.
55+
If the `action` throws an error or returns a rejected Promise, React reports
56+
the error as uncaught, and an Error Boundary does not handle it. To let the
57+
nearest Error Boundary handle these errors, use the `startTransition`
58+
function returned by
59+
[`useTransition`](/reference/react/useTransition#displaying-an-error-to-users-with-error-boundary).
5560

5661
* 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.
5762

@@ -94,7 +99,11 @@ With a Transition, your UI stays responsive in the middle of a re-render. For ex
9499

95100
<Note>
96101

97-
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.
102+
`startTransition` does not provide the `isPending` flag. Call it from code that
103+
cannot call Hooks, such as data-library code outside a component. Unlike the
104+
function returned by [`useTransition`](/reference/react/useTransition), the
105+
standalone `startTransition` is not associated with a component. As a result,
106+
an Error Boundary cannot handle errors from its Action. [See Caveats.](#caveats)
98107

99108
[Learn about Transitions and see examples on the `useTransition` page.](/reference/react/useTransition)
100109

‎src/content/reference/react/useTransition.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1567,7 +1567,12 @@ main {
15671567
15681568
### Displaying an error to users with an error boundary {/*displaying-an-error-to-users-with-error-boundary*/}
15691569
1570-
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.
1570+
The `startTransition` function returned by `useTransition` is associated with
1571+
the component that called the Hook. If the Action passed to `startTransition`
1572+
throws an error or returns a rejected Promise, the nearest
1573+
[Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
1574+
can handle the error. Wrap the component that calls `useTransition` in an Error
1575+
Boundary to display a fallback for these errors.
15711576
15721577
<Sandpack>
15731578
@@ -1738,7 +1743,11 @@ This is a JavaScript limitation due to React losing the scope of the async conte
17381743
17391744
### I want to call `useTransition` from outside a component {/*i-want-to-call-usetransition-from-outside-a-component*/}
17401745
1741-
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.
1746+
You can't call `useTransition` outside a component because it's a Hook. In this
1747+
case, use the standalone [`startTransition`](/reference/react/startTransition)
1748+
function instead. It marks state updates as Transitions but does not provide the
1749+
`isPending` flag. Because the standalone function is not associated with a
1750+
component, an Error Boundary cannot handle errors from its Action.
17421751
17431752
---
17441753

0 commit comments

Comments
 (0)