Skip to main content

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

useItemRating

Fetches the average rating and total number of ratings for a specific item. The query is gated behind the ratings feature flag -- when the flag is disabled, no network request is made and the hook returns zero defaults.

Source: template/hooks/use-item-rating.ts

Exported Hooks​

HookPurpose
useItemRatingFetch rating data (average and count) for a single item

Signature​

function useItemRating(itemId: string, enabled?: boolean): UseItemRatingReturn;

Parameters​

ParameterTypeDefaultDescription
itemIdstring—Required. The item ID to fetch ratings for.
enabledbooleantrueAdditional enable flag (combined with the ratings feature flag).

Return Values​

const {
  rating,     // RatingData -- { averageRating: number; totalRatings: number }
  isLoading,  // boolean -- True while fetching
  error,      // Error | null -- Fetch error if any
  refetch,    // () => void -- Manually re-fetch rating data
} = useItemRating(itemId);

RatingData Shape​

interface RatingData {
  averageRating: number;   // Average score (e.g. 4.5)
  totalRatings: number;    // Number of ratings submitted
}

The default value when no data is loaded is { averageRating: 0, totalRatings: 0 }.

Cache Configuration​

SettingValue
Query key['item-rating', itemId]
staleTime5 minutes
refetchOnMountfalse
refetchOnWindowFocusfalse
refetchOnReconnectfalse
enabledfeatures.ratings && enabled

Implementation Details​

  • Feature flag gated: The query's enabled flag is features.ratings && enabled. When the ratings feature is turned off in the application's feature flags, the hook short-circuits and returns the default { averageRating: 0, totalRatings: 0 } without any network request.
  • No HTTP cache: The fetch function passes cache: 'no-store' and a Cache-Control: no-store header to prevent stale browser-level caching. Freshness is managed entirely by React Query's stale time and explicit refetch calls.
  • Abort signal: The query function accepts and forwards the signal from React Query, enabling automatic cancellation of in-flight requests when the component unmounts or the query is invalidated.
  • Conservative refetch policy: All automatic refetch triggers (refetchOnMount, refetchOnWindowFocus, refetchOnReconnect) are disabled. Rating data only refreshes when the staleTime expires or when refetch is called explicitly, typically after a user submits a new rating.
  • Client component: This hook is marked with 'use client' and should only be used in client components.

Usage: Star Rating Display​

function ItemRatingDisplay({ itemId }: { itemId: string }) {
  const { rating, isLoading } = useItemRating(itemId);

  if (isLoading) return <Skeleton className="h-5 w-24" />;

  return (
    <div className="flex items-center gap-2">
      <StarRating value={rating.averageRating} readOnly />
      <span className="text-sm text-muted-foreground">
        {rating.averageRating.toFixed(1)} ({rating.totalRatings} ratings)
      </span>
    </div>
  );
}

Usage: Refresh After Rating Submission​

function RatingForm({ itemId }: { itemId: string }) {
  const { rating, refetch } = useItemRating(itemId);

  const handleSubmitRating = async (value: number) => {
    await submitRating(itemId, value);
    // Explicitly refresh after the user submits a rating
    refetch();
  };

  return (
    <div>
      <p>Current: {rating.averageRating.toFixed(1)}</p>
      <StarRating
        value={0}
        onChange={handleSubmitRating}
      />
    </div>
  );
}

Usage: Conditional Rendering Based on Feature Flag​

function ItemDetailSidebar({ itemId }: { itemId: string }) {
  const { rating, isLoading } = useItemRating(itemId);

  // When the ratings feature flag is off, rating stays at defaults
  // and isLoading is false, so nothing renders
  if (rating.totalRatings === 0 && !isLoading) return null;

  return (
    <div className="p-4 border rounded">
      <h4>Rating</h4>
      <span>{rating.averageRating.toFixed(1)} / 5</span>
      <span className="text-sm ml-1">({rating.totalRatings})</span>
    </div>
  );
}

Dependencies​

DependencyPurpose
@tanstack/react-queryuseQuery for data fetching and caching
@/lib/api/server-api-clientserverClient for API calls, apiUtils for response validation
@/hooks/use-feature-flags-with-simulationuseFeatureFlagsWithSimulation for the ratings feature flag