Retry suspense queries
A suspense query throws into a React error boundary and the fallback offers a retry button.
TanStack · Class
QueryErrorResetBoundary
QueryErrorResetBoundary scopes query-error resets to a component subtree. Give its render-prop reset function to an error boundary so a retry action can clear query errors before rendering again.
How it works
QueryErrorResetBoundary provides a reset function to descendant content. Pair that function with a React error boundary so a user-triggered reset clears query errors and allows queries using suspense or throwOnError to try again during a later render.
Syntax
function QueryErrorResetBoundary(props: QueryErrorResetBoundaryProps): Element;Parameters
| Name | Type | Description |
|---|---|---|
children | ReactNode | QueryErrorResetBoundaryFunction | Either rendered content or a function receiving QueryErrorResetBoundaryValue and returning rendered content. |
Returns
Element containing the supplied children.
Key points
- Reset behavior is scoped to queries inside the component boundary.
- The required children prop supplies the UI contained by the reset boundary.
- Children may be a React node or a render function that receives the boundary reset value.
- The component renders plain children directly and calls function children with the boundary value.
- The component accepts QueryErrorResetBoundaryProps and returns a React Element.
Common mistakes
- Use this boundary when query errors are surfaced through suspense or throwOnError; ordinary rendering does not by itself require this reset coordination.
Example: Retry failed queries from an error boundary
import { QueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'
export function App() {
return (
<QueryErrorResetBoundary>
{({ reset }) => (
<ErrorBoundary
onReset={reset}
fallbackRender={({ resetErrorBoundary }) => (
<button onClick={resetErrorBoundary}>Try again</button>
)}
>
<Page />
</ErrorBoundary>
)}
</QueryErrorResetBoundary>
)
}Connects a React error boundary's reset action to TanStack Query's query-error reset function.
When to use it
Recover from thrown query errors
Queries configured with throwOnError need coordinated recovery after an error fallback is reset.
Scope recovery to a subtree
Several related queries should share a reset lifecycle within one page or widget.
Interview questions
QWhat problem does QueryErrorResetBoundary solve?
It is a React component that scopes query-error resetting to its boundary. Its children may be a render function receiving a reset value, which can be passed to an error boundary's onReset callback.
Follow-up: How does the hook differ? useQueryErrorResetBoundary resets errors in the closest component boundary, or globally when no boundary exists.
QHow is it wired to an error boundary?
Use the component around the content whose query errors should be reset. Render-prop children receive reset, and the error boundary invokes that function when its fallback is reset.
Follow-up: Why connect onReset rather than only the fallback button? Because the error-boundary reset lifecycle is the event that should coordinate the query reset and the component re-render.
QWhat does the children prop accept?
The component's children can be either a plain React node or a function receiving QueryErrorResetBoundaryValue. The rendered result is either returned directly or produced by calling that function.
Follow-up: What does the value currently expose? The documented example uses its reset function to clear query errors.
Related
QueryErrorResetBoundaryPropsQueryErrorResetBoundaryFunctionQueryErrorResetBoundaryValueuseQueryErrorResetBoundarythrowOnError