Query Boundary

npx shadcn@latest add https://shuip.plvo.dev/r/rhf-query-boundary.json

pnpm dlx shadcn@latest add https://shuip.plvo.dev/r/rhf-query-boundary.json

bun x shadcn@latest add https://shuip.plvo.dev/r/rhf-query-boundary.json

'use client';

import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { AlertTriangle, RefreshCcw } from 'lucide-react';
import * as React from 'react';
import { ErrorBoundary, type FallbackProps } from 'react-error-boundary';
import { Button } from '@/components/ui/button';

interface QueryBoundaryProps {
  children: React.ReactNode;
  queryKeys?: string[];
  loadingFallback?: React.ReactNode;
  errorFallback?: (props: FallbackProps) => React.ReactNode;
}

export function QueryBoundary({
  children,
  queryKeys = [],
  loadingFallback = 'Loading...',
  errorFallback,
}: QueryBoundaryProps) {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={(props) =>
            errorFallback ? errorFallback(props) : <DefaultErrorFallback {...props} queryKeys={queryKeys} />
          }
        >
          <React.Suspense fallback={loadingFallback}>{children}</React.Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}

export function DefaultErrorFallback({
  error,
  resetErrorBoundary,
  queryKeys = [],
}: FallbackProps & { queryKeys?: string[] }) {
  return (
    <div className='p-6 rounded-lg border border-destructive/30 bg-destructive/5 flex flex-col items-center justify-center space-y-4 text-center'>
      <AlertTriangle className='text-destructive size-12' />
      <div>
        <h3 className='text-lg font-semibold mb-2'>Oops, something went wrong!</h3>
        <p className='text-muted-foreground'>{error.message || 'Unexpected error'}</p>
        {queryKeys.length && (
          <p className='text-xs text-muted-foreground mt-2'>
            Concerned quer{queryKeys.length > 1 ? 'ies' : 'y'}: {queryKeys.join(', ')}
          </p>
        )}
      </div>
      <Button onClick={resetErrorBoundary} variant='outline' className='gap-2'>
        <RefreshCcw className='size-4' />
        Retry
      </Button>
    </div>
  );
}

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 (
    <QueryBoundary 
      queryKeys={['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>
  );
}

<QueryBoundary 
  queryKeys={['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

Prop

Type