Query Boundary
Error boundary and suspense wrapper for TanStack Query with automatic error recovery and loading states.
npx shadcn@latest add https://shuip.plvo.dev/r/rhf-query-boundary.json
Preview
User Data
This component is wrapped in a QueryBoundary for error handling.
QueryBoundary
is a wrapper component that combines TanStack Query's error handling with React Suspense for comprehensive query state management. It automatically catches query errors, displays loading states, and provides retry functionality.
The component eliminates the need to manually wrap components with multiple boundary providers. It handles both synchronous errors and async query failures with a unified interface and consistent error recovery patterns.
Built-in features
- Automatic error catching: Captures both sync and async query errors
- Suspense integration: Built-in loading state management with React Suspense
- Error recovery: One-click retry functionality with query reset
- Customizable fallbacks: Override default loading and error UI components
- Query key tracking: Optional debugging information for failed queries
Basic usage
Wrap components that use TanStack Query hooks:
import { QueryBoundary } from '@/components/ui/shuip/query-boundary';export default function App() {return (<QueryBoundaryqueryKeys={['users']}loadingFallback={<div>Loading users...</div>}><UsersList /></QueryBoundary>);}function UsersList() {const { data } = useQuery({queryKey: ['users'],queryFn: fetchUsers});return <div>{data.map(user => user.name)}</div>;}
Custom error handling
Override the default error fallback for custom error UI:
function CustomErrorFallback({ error, resetErrorBoundary }) {return (<div className="text-center p-8"><h3 className="text-lg font-semibold mb-2">Something went wrong</h3><p className="text-muted-foreground mb-4">{error.message}</p><button onClick={resetErrorBoundary}>Try again</button></div>);}<QueryBoundaryqueryKeys={['users', 'posts']}errorFallback={CustomErrorFallback}loadingFallback={<div>Loading...</div>}><Dashboard /></QueryBoundary>
Default error fallback
The built-in error fallback includes:
- Error icon and message display
- Query key debugging information
- One-click retry functionality
- Consistent styling with your design system
Props
Name | Type | Description |
---|---|---|
children | React.ReactNode | The child components to wrap in the boundary. |
queryKeys | string[] | The query keys to monitor for debugging (optional). |
loadingFallback | React.ReactNode | The fallback to display during loading (default: "Loading..."). |
errorFallback | (props: FallbackProps) => React.ReactNode | The custom fallback to display on error (optional). |