API Reference

UIStatesProps

Complete interface for the UIStates component:

typescript

interface UIStatesProps {
  // Data and state
  data?: unknown;
  loading?: boolean;
  error?: Error | null;

  // TanStack Query integration
  query?: QueryLike;

  // Content
  children: ReactNode;

  // Empty state
  emptyState?: ReactNode;
  emptyCheck?: (data: unknown) => boolean;

  // Error state
  errorState?: ReactNode | ((error: Error, retry?: () => void) => ReactNode);

  // Skeleton caching
  enableCache?: boolean;
  cacheKey?: string;

  // Advanced
  className?: string;
}

Prop Details

Prop	Type	Default	Description
data	unknown	undefined	The data to render (null/undefined during loading)
loading	boolean	false	Whether data is currently loading
error	Error \| null	null	Error object if fetch failed
query	QueryLike	undefined	TanStack Query result object
children	ReactNode	required	Content to render when data exists
emptyState	ReactNode	Default UI	Custom empty state component
emptyCheck	function	Array.isArray(data) && data.length === 0	Function to determine if data is empty
errorState	ReactNode \| function	Default UI	Custom error state
enableCache	boolean	false	Enable skeleton caching
cacheKey	string	undefined	Unique key for cache storage
className	string	undefined	CSS class for wrapper div

QueryLike

Interface for TanStack Query-compatible objects:

typescript

interface QueryLike {
  data?: unknown;
  isLoading?: boolean;
  error?: Error | null;
  refetch?: () => void;
}

UIState

Internal enum representing current UI state:

typescript

enum UIState {
  Loading = "loading",
  Error = "error",
  Empty = "empty",
  Success = "success",
}

SkeletonNode

Internal type representing a measured DOM element for skeleton generation:

typescript

interface SkeletonNode {
  type: "text" | "block" | "image";
  width: number;
  height: number;
  x: number;
  y: number;
  fontSize?: number;
  borderRadius?: number;
}

State Priority

UI States determines which state to show in this order:

Loading: If loading is true
Error: If error exists and loading is false
Empty: If emptyCheck returns true and loading is false
Success: If data exists and none of the above

Complete Example

typescript

import { UIStates } from "@promise-inc/ui-states";
import { useQuery } from "@tanstack/react-query";

function ProductGrid() {
  const query = useQuery({
    queryKey: ["products"],
    queryFn: fetchProducts,
  });

  return (
    <UIStates
      // State management
      query={query}

      // Empty state
      emptyCheck={(data) => !data?.items?.length}
      emptyState={
        <div className="text-center py-12">
          <p>No products found</p>
        </div>
      }

      // Error state
      errorState={(error, retry) => (
        <div className="text-center py-12">
          <h3 className="text-red-600">{error.message}</h3>
          <button onClick={retry}>Retry</button>
        </div>
      )}

      // Caching
      enableCache={true}
      cacheKey="product-grid"

      // Styling
      className="container mx-auto"
    >
      <div className="grid grid-cols-3 gap-4">
        {query.data.items.map(product => (
          <ProductCard key={product.id} product={product} />
        ))}
      </div>
    </UIStates>
  );
}

Tailwind CSS Setup