react-query-handler

A flexible React component and hook for handling async query states with customizable loading, error, and empty states.

Installation

npm install react-query-handler
# or
yarn add react-query-handler

Features

• 🎯 Simple component and hook-based API
• 🎨 Customizable loading, error, and empty states
• 🔄 Compatible with any async data fetching solution
• ⚙️ Global default components via context
• 🎁 TypeScript support out of the box

Usage

Basic Component Usage

import { QueryHandler } from 'react-query-handler';

function MyComponent() {
  const query = useQuery('todos', fetchTodos);

  return (
    <QueryHandler query={query}>
      {/* Your content here */}
      {query.data.map(todo => (
        <div key={todo.id}>{todo.title}</div>
      ))}
    </QueryHandler>
  );
}

Hook Usage

import { useQueryHandler } from 'react-query-handler';

function MyComponent() {
  const query = useQuery('todos', fetchTodos);
  const content = useQueryHandler(query);

  // If in loading/error/empty state, appropriate component will be returned
  // Otherwise, content will contain your data
  return <div>{content}</div>;
}

Custom Components

function MyComponent() {
  return (
    <QueryHandler
      query={query}
      loadingComponent={<CustomSpinner />}
      errorComponent={<CustomError />}
      emptyComponent={<CustomEmpty />}
    >
      {/* Your content here */}
    </QueryHandler>
  );
}

Global Defaults

import { QueryHandlerProvider } from 'react-query-handler';

const config = {
  defaultLoadingComponent: <CustomSpinner />,
  defaultErrorComponent: <CustomError />,
  defaultEmptyComponent: <CustomEmpty />
};

function App() {
  return (
    <QueryHandlerProvider config={config}>
      {/* Your app content */}
    </QueryHandlerProvider>
  );
}

API Reference

QueryHandler Component

Props

| Prop | Type | Description | |------|------|-------------| | query | IQueryResult<T> | Query result object containing loading/error states and data | | loadingComponent | ReactNode | Optional custom loading component | | errorComponent | ReactNode | Optional custom error component | | emptyComponent | ReactNode | Optional custom empty state component | | children | ReactNode | Content to render when query is successful |

useQueryHandler Hook

const content = useQueryHandler(query, {
  loadingComponent,
  errorComponent,
  emptyComponent
});

Returns appropriate component based on query state or the data if query is successful.

QueryHandlerProvider

Props

| Prop | Type | Description | |------|------|-------------| | config | IQueryHandlerConfig | Configuration object for default components | | children | ReactNode | Child components |

Types

interface IQueryResult<T> {
  isLoading: boolean;
  isError: boolean;
  isSuccess: boolean;
  data?: T;
  error?: Error;
}

interface IQueryHandlerConfig {
  defaultLoadingComponent?: ReactNode;
  defaultErrorComponent?: ReactNode;
  defaultEmptyComponent?: ReactNode;
}

Compatibility

Works with any data fetching solution that provides loading, error, and success states (React Query, SWR, Apollo, etc.).

License

MIT