Skip to content

Commit 409451a

Browse files
committed
Clarify standalone startTransition error handling
1 parent 0006861 commit 409451a

2 files changed

Lines changed: 5 additions & 3 deletions

File tree

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ 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).
55+
5456
* 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.
5557

5658
* 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
9294

9395
<Note>
9496

95-
`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.
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.
9698

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

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1567,7 +1567,7 @@ main {
15671567
15681568
### Displaying an error to users with an error boundary {/*displaying-an-error-to-users-with-error-boundary*/}
15691569
1570-
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.
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.
15711571
15721572
<Sandpack>
15731573
@@ -1738,7 +1738,7 @@ This is a JavaScript limitation due to React losing the scope of the async conte
17381738
17391739
### I want to call `useTransition` from outside a component {/*i-want-to-call-usetransition-from-outside-a-component*/}
17401740
1741-
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.
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.
17421742
17431743
---
17441744

0 commit comments

Comments
 (0)